7 Deadly Sins of Technical Writing

    As a writer, I have created documentation that I am proud of but I have also created some that were not up to the mark. Here are seven problems to look out for: 
    1. Poor Organization: Make sure that your users can easily find the information. It is tempting to organize the content as per what you see in the software application. But ideally, you must ask what the user wants and based on that you must organize your content. 
    2. Inaccurate information: Sometimes you may receive wrong information from Engineers and document this piece of information. To fix this issue, you must get your content reviewed by key stakeholders like product owners, scrum masters, engineers, and QA guys to check the veracity of the content. 
    3. Outdated information: This occurs when the product undergoes enhancement but the changes are not communicated to the writers by the development team.
    4. Incomplete information: Users often need more information than you give them. You must not only document how to perform any task, but also provide conceptual information answering what, when, and why. Your goal should be to tell the users everything they need to know without overwhelming them.
    5. Bad sentence structure: The general rule of thumb for technical documents is keeping your sentences short. Whenever possible, use tables, bullet points and numbered lists to organize information.
    6. Poor word choices: There are many words that mean approximately the same thing. Depending on the situation, you must make the judgment. When choosing between one or more words ask the following questions:

      Which word is the most clear?
      Which word is the most unambiguous?
      Which word is the most accurate?

      Once you have made a choice, the next step is to be consistent. Use the same word every time the situation and instructions are the same. For example, if you wrote,
      Click the OK button or Click OK, the first time, use the same statement every time you expect the same action. 
    7. Incomplete Review: Never take your writing for granted if your document has not undergone peer and technical review. You will be surprised to come across errors after review. So it’s worth the effort to get your documents first reviewed by a fellow technical writer and then by Engineers/QA/PLMs. During peer review, you can catch some good errors like missing links or broken cross-references which are normally missed out in the technical review.

    No comments:

    Post a Comment