Technical Documentation Review and Tips

Life doesn’t come with an instruction manual

BUT

Calsoft Products and Services DO!

Analysis, design, development, quality analysis, and technical publication are the most significant phases of product development. A product release is incomplete without the supporting technical documents though the documents may never be used. These documents are often requested so that they may be referred to in the near future. Hence, it is important to develop technical documents that add value to the product.

Challenge

The biggest challenge is to introduce documentation practices in a project right from the beginning as it helps in providing quality technical documents. After a lot of effort, the first draft of your document is ready; the only thing left is to have it reviewed for content verification and completeness. Though it sounds pretty easy, but there are plenty of challenges during this process.

Best Practice

Creating technical document is a collaborative process that involves the writer and the reviewer. By setting up documentation practices, the documents enhance the product value. Preparing drafts and their reviews go hand-in-hand so both the stages are equally important in the document development life cycle.

Review is a continuous evaluation process that focuses on the functional elements of a document. It allows SMEs to add information that may not be available to the writer. To do this, the following are a must:

• Identifying the SME and mandatory reviewers
• Getting timely input from SMEs
• Getting timely feedback from reviewers
• Resolving conflicting feedback early
• Limiting review cycles

Quick tips

The first step of including documentation practice is to proofread the technical documents. Proofreading is the final check for errors on the printed text prior to publication and adds value to any piece of document. Proofreaders need to have an eagle’s eye to identify mistakes such as spelling mistakes not identified by spell checker, checking complete sentences, punctuation errors, typos, etc.

Proofreading

• Present technically correct, logical, and complete piece of information that meet customer and stakeholder requirements.
• Review, update, and get an approval prior to publishing a document
• Define changes and revision status of documents for quick reference.
• Maintain version control so that documents are easily available.
• Prepare a checklist that is mandatory for proofreading.
• Execute spell check.

Do’s

• Know your audience well and refer to a prescribed standard of style.
• Pre-write the content to understand the flow and gaps of knowledge at your end.
• Make use of active verbs to convey the clear sets of steps or processes.
• Make use of clear, unambiguous words.
• Smooth transition between any two topics and maintain a flow for better comprehension.
• When you are using tables or figures, make sure the data is valid. Present the data in a table or a list.
• Give a thorough review to the entire content and re-write sections if they can be presented better.
• Look for mistakes, typos, breaks in logic, ambiguity, etc.

DON’Ts

• Do not use abbreviations unless specified to do so.
• Do not use long noun strings in order to modify the last noun of a sentence.
• Do not repeat the obvious conclusion of an action.
• Do not rush to send the content for publishing without review.
• Avoid writing long paragraphs, instead use bullet lists.

Grammar and style

• Comprehensible, simple structure, and conciseness
• Spellings
• Active vs. passive voice
• Parallelism
• Articles
• Punctuation
• Use of bulleted and numbered lists where possible
• Consistency in the use of terms, product names, component names, and headings

Review process

The review process mainly consists of the following steps:

1. Mandatory self-review
   • Macro level review that includes document structure and layout
   • Micro level review that consist of sentence structure, grammar, punctuation, and style are correct
   • Engross yourself in the review.
   • Review from a user’s perspective and from the translation and localization perspective.
2. Peer review/Technical review is compulsory
   • Bring to attention the shortcomings, errors, and mistakes.
   • Respond politely.
   • Micro level review that consist of sentence structure, grammar, punctuation, and style are correct

3. Editorial review
   • Comprehensible, simple structure; conciseness
   • Spellings
   • Active voice usage, parallelism, articles, punctuation
   • Use of bulleted and numbered lists where possible
   • Consistency in the use of terms, product names, and component names
   • Consistency in headings
   • The document has followed the style guide

4. Final document sanity with the checklist and verify if all review comments are incorporated.

Questions that must be asked during a review

4. • Does the document cover the defined scope?
   • Does the document conform to the documentation standards of the style guide?
   • Is the approach logical and understandable?
   • Are the chapters, sections, and paragraphs properly organized and structured?
   • Are the contents technically correct?
   • Is the language and style clear, concise, consistent, and comprehensible?
   • Are there grammar, spelling, and punctuation errors?
   • Are all the cross-references accurate? Are all the links working?
   • Is the document formatted correctly?

Summary

Technical reviews are vital for effective and quality documentation. To make this happen, have documentation and its reviews listed as one of the deliverables – just like development or testing. This will place priority on the process, and ensure everyone involved understands the importance of proper and thorough reviews. Identify the right SMEs, and plan review cycles. This way, everyone knows what they have to do when, and can manage their time around other projects and deliverables.

Skilled writers are an asset to the development team as they ask the right questions from reviewers, understand what they want in the document, and finally filter the information to suit customer’s requirements.

[Tweet “Technical Documentation Review and Tips ~ via @CalsoftInc”]

Looking for skilled technical writers for the technical documentation of your products and services?