Technical Authors | what does good look like

What does good look like? 

How do we establish a shared understanding and define what ‘Good’ looks like for presenting information in an organisation? Everyone has a different opinion. If we cannot apply what good looks like, it results in problems in writing and preparing technical documents. 

The question touches on a common scenario in the tech industry. We have individuals or teams writing technical documentation. They shun our expertise because they want to look good. This approach leads to mixed outcomes when the document writer needs more skills. So, what does good look like?

Here’s a deeper look into the dynamics of this situation:

Self-Assessment vs. Professional Standards

    • Confidence vs. Competence: non-technical authors write technical documentation based on their understanding of the subject matter. However, good technical documentation requires more than just subject matter expertise; it requires the ability to present information accessibly.
    • Underestimating the Skill Set: Technical writing requires clear communication and deep technical knowledge. It also involves understanding the user’s perspective. That can be challenging for those deeply ingrained in the technical details of a product.

Feedback and Improvement

    • Receiving Critique: When non-specialists craft technical documents, professional technical authors’ feedback can highlight the lack of clarity, conciseness, organisation, and user focus. This critique improves the documentation’s effectiveness and is not a personal insult.
    • The Value of Expertise: Professional technical authors bring specialised skills, including
      • audience analysis,
      • information architecture,
      • writing clarity, and
      • the ability to distil complex information into understandable content.

Their expertise is in writing and understanding how people search for, comprehend, and use technical information.

Recognising Good Technical Documentation

      • Clarity and Conciseness: Good documentation conveys complex information easily, avoiding unnecessary jargon and focusing on what the user needs to know.
      • Organisation and Accessibility: It is well-structured, making it easy for users to find the information they need. Good documentation anticipates user questions and provides answers in a logical flow.
      • Accuracy and Reliability: It must be technically accurate and up-to-date, giving users confidence in its instructions and information.

The Role of a Good Technical Author

An excellent technical author bridges the gap between complex technicalities and user comprehension. They:

      • Understand the technology and the audience.
      • Skilled in creating helpful content.
      • Employ best practices in technical communication to ensure documentation is adequate.

Conclusion

Our standards, specialised skills and perspectives separate us from the self-assessed Competence. Recognising the value of this expertise enhances the quality of technical documentation. Understanding what good technical documentation looks like—and the role of a technical author in achieving it—is crucial for anyone involved in creating or overseeing the creation of technical documents.

That’s what ‘Good’ looks like!

 

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.