Document Review

– Sharada Palagummi

This article is meant for writers who are just trying to find their feet in the technical writing field. I will take a couple of excerpts from some user documentation, and will discuss them. Some points might be not acceptable and many might be missing. My purpose is simply to set off a thought process.
Remember, the most important reader of a manual or help is the user who uses the product. The product may be hardware or software. It may be a desktop product or a handheld product. The user may be a common man or a high-tech programmer. In any case, our primary duty is to this “user”.
While writing to help the user, keep 4Cs in mind: Correct, Clear, Crisp, and Consistent.

Example 1 [From the Absolute Beginners Guide to Getting Started with WordPress. This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License]

What I liked

• Content is very clear; no ambiguity
• Content is helpful to the user
  • Reassurance that the appearance of unwanted boxes is normal behavior
  • Explanation of the cause for it
  • Suggestion to solve it
• Content is made easy to understand
  • Use of figures to show a sample file
  • Indicators (arrows) to highlight the point

What I wished were better

• Language
  • Spelling mistake: carraige instead of carriage.
  • Punctuation:
    • W of Windows should be in upper case. Windows is the name of an operating system; W must be always in upper case.
    • Similarly, Notepad is the name of a software tool; N must be always in upper case.
    • In …formatting of the file Which will, the letter W of which should be in lower case.
    • Missing commas: For example, in To correct this open the file, I’d use a comma after this.
  • Tenses: Use of future tense instead of simple present.
    As most style guides recommend, simple present tense helps the reader understand quickly; avoid all other tenses.
  • Simplicity: Use of unnecessary words
    • This is normal. It is caused by the fact that Unix, Macintosh and PC operating systems all represent carraige returns with different codes could be written as It is because Unix, Macintosh and PC operating systems represent carriage returns with different codes or as It is because carriage return is represented differently in Unix, Macintosh and PC operating systems.
    • In This will … Which will then appear like this, the word then is not necessary.
  • Clarity: Use pronouns only if what they refer to is crystal clear. In This will correctly interpret and save the proper formatting of the file Which will then appear like this
    • What is denoted by this is not clear.
    • What is denoted by Which is not clear.
  • Correctness:
    In This will correctly interpret and save the proper formatting of the file Which will then appear like this
    • It is not the act of saving and closing that interprets correctly; it might be the Notepad software.
    • What is being done is the correct interpretation and display of the carriage returns; not the formatting of the file.
• Presentation
  • The curved yellow arrows are rather big and distracting.
  • The text mentions lack of word wrapping, but the figure fails to indicate all the text being in a single line.

Example 2 [From VideoLAN Wiki: VLC Usage. VideoLAN is an open source multimedia player and a server to stream live and on-demand video to network and the Internet.]

What I liked

• Content is clear; no ambiguity.
• Content is helpful to the user.
  • Knowledge is shared with the reader about concepts such as playlist, podcast, SAP announcement, and shoutcast.
  • Explanation of concepts and features is brief, clear, and without jargon. The purpose of the features is made clear to the readers.
  • Procedures are explained clearly with only the necessary content.
• Structure of the content: Good with a brief explanation of the feature and procedure to use it.

What I wished were better

• Language
  • Punctuation: After phrases like To add a Podcast URL and To add a Shoutcast radio listing, semicolons are missing.
  • Proofing could be more rigorous. For example, in Step 3, there is an unnecessary article, the, before the name of an option and in 5c, the word Specifying is repeated.
• Presentation
  • The screenshot lacks helpful data; the duration is zero for all the items.
  • The screenshot does not exactly correspond to the explanation.
  • There is no caption after the screenshot.
  • In Step 5, options are written as if they are sub-steps of a procedure; actually, they are not.
  • The buttons at the bottom are not explained.

What I have mentioned are very basic points. After reading this, try to find more points about these excerpts. More importantly, try to avoid such errors before you make a delivery and try to ensure you covered the good points; don’t expect your customer or boss to find these simple errors.

About the author:
Sharada Palagummi works with Integra Micro Systems. She has more than 23 years of experience in technical writing, localization and teaching Statistics to undergraduates. She has done courses in French, Italian, Japanese and Chinese. You can contact her at sharada.kalapatapu@gmail.com.

About the illustration:
The image is used with permission from Mallika Yelandur.