Best Practices that Improve the Quality of Documentation

Documentation is now treated as a product because prospective customers use it to understand how an actual product will work before they can buy it. So it is not surprising to see decision takers, managers or end-users going through online help that is listed in the public domain before making a buying decision.

Poor documentation can ruin a good product because users cannot get the right information, in the right way to understand the product. For example, nowadays the developers can make API calls from the document itself to test the APIs, before subscribing or buying the API service or product.

Poor documentation confuses users and discourages them from buying the product.

On the other hand, good documentation with a frictionless user journey encourages users to try out the product and even buy it. 

Create a Robust Documentation Roadmap

As a technical writer, you must create robust documentation roadmap before you start documenting the product. Ask yourself – what, why, how, when and for whom - you will document

1. "What" defines the application, product, process or service you have to document.

2. "Why" defines whether it is necessary or not necessary to document. For example, an application can be self-explaining; is simple to use and does not require help. That is not the case when an application is complex and requires a help guide.

3. "Who" defines the target audience, whether the document is to be written for layperson, engineers or developers. You must use the right language and terminology for the target audience.

4. "How" defines the documentation methodology, documentation tools, and team hierarchy.

5. "When" defines the timeline of the entire documentation process and the deadline.

Use Plain Language

As technical documents tend to be descriptive and complex, using plainer words or terms, eliminates the chance of users not understanding or misinterpreting the information, and wrongly using the product or service. This is also true for translators because they can also misinterpret the information and deliver the translation that is not contextual to the original document in English.

Plain words and shorter sentences convey information clearly, unlike longer sentences, which tend to confuse. This speeds up understanding of the content and reduces translation time, which in turn reduces the cost of translation

Simpler, commonly-used words or terms in the document improve its comprehensibility, making it easy to understand each word and translate with few or no errors compared to a document that is not written in plain English.

An error-free translated document enables users to use a product or service in the right and safe manner. It prevents mishaps, accidents or damage that can happen because of incorrect or unsafe actions taken by users, guided by a wrongly translated document.

Benefits of Plain Language

As a writer you are able to:

· Explain complex subject in an easy-to-understand language.

· Simplify technical documents and improve readability.

· Eliminate words, sentences or phrases that can confuse readers.

 As a reader, you are able to

· Quickly grasp the information.

· Easily understand complex technical subject matter without any confusion.

As a translator, you are able to:

· Understand and translate each word correctly, and maintain contextuality.

· Reduce time and cost of translation. 

A human translator is more accurate and reliable than machine translation because the machine lacks the wit, logic, emotion intelligence needed to translate 100% contextually accurate content. As one word can have two or more meanings, the machine cannot always use the right translated word that perfectly describes an action. Translation errors can damage life and property, and seriously damage the reputation of the company, even causes a monetary loss in millions. 

Use Right Words

Words make sentences, and sentences make your document. When you write a document, choose concrete and specific words that help you effectively communicate with readers. Here are word-choice tips that enable you to write an effective technical document.

• Choose words your readers understand and help you to increase your communication's persuasiveness.
• Use specialized terms when - and only when - your readers will understand.
• Use words accurately. Prefer plain words over fancy ones. Example - use "end" instead of "terminate".
• Use the same word each time to refer the same thing.
• Avoid slang words and idioms. Do not use acronyms your readers won't understand.
• Use nouns and pronouns that are gender-neutral. Example - use "synthetic" instead of "manmade".

Simplify the Complex

As a writer, it is your primary responsibility to write documents that are easy to comprehend. This is what I put into practice when I write technical documents.

•  Practice Minimalism - Why use 3 words when you can say it in 2 words. Maintain brevity, without sacrificing the completeness of the information.
•  Provide Required Information only - Provide information that users need, not what you want them to read. This prevents information overload.
• Support Text with Visual Clues - Helps readers to scan and grasp complex information quickly.
• Improve Readability - Increase white space and use the right fonts for body text and headings. Divide the document into chunks of information and highlight the important information.
• Be Consistent - Use same words or terms to describe same action, feature or concept throughout the document. Consistency builds readers' trust in the author.
• Structure content as chunks of information - Use bullets, numbered lists and white space to improve readability.
• Use verbs at the beginning of the sentence to make it actionable.

Use Right Verbs and Make Your Document Actionable

When you are documenting a product, service, application or process, use the right verb to describe a specific action. The verb should be highly contextual to the action it describes. Choose the perfect word that correctly describes an action and the result that user will get from that action he or she takes.

For example, presented below are two commands or actions.

1. Click to DELETE the file from your device.

2. Click to REMOVE the file from your device

The words "delete" and "remove" in both commands seem to do the same thing. But they do not.

If you want a user to permanently wipe out the data from his or her device and not recover it, then instruct him or her to use command no.2 - "Click to REMOVE the file from your device"

If you want a user to wipe out data temporarily and recover it later, then instruct him or her to use the command no. 1- “Click to DELETE the file from your device."

You can see that words “delete" and "recover" have a specific meaning in context to the action a user takes to get the desired result.

Use Graphics to Support Text

If a help guide or technical document is devoid of diagrams, screenshots, flow diagrams or other visual representation that aid text, it becomes difficult to understand the subject. Visual clues speed up understanding of the complex, technical subject. Always use visual clues with text in quick start guides, user manuals, and step-by-step guides.

Graphics are diagrams, flowcharts, tables, screenshots, photographs, icons, and other visual representation. They help improve the quality of a technical document in the following ways.

• Speed up the understanding of the complex technical subject.
• Help readers gain more knowledge about a product, application or service.
• Enhance document’s visual appeal and thus improve the reader’s concentration on its message.
• Convey information to the readers, who do not share a common language with writers.

Visual content can be used in a technical document to show:

• How a product works.
• Readers/users to do something. For example, explain a process or how to use a product
• How something is constructed.
• Complex data in an easy to understand and useful manner. For example, data in tabular format
• Information through icons to readers with different language background or reading disability.
• Trends or other numerical relationships through line graphs, pie-charts, bar graphs, etc.

Revise the Final Draft

• Correct the errors in key statements.
• Fix issues in the structure of the document to improve the logical flow of information.
• Correct misspellings.
• Revise tangled sentences though you can understand them.
• Rectify grammatical mistakes.
• Double-check for any missing information.
• Double-proof read the document.

Conclusion

Technical documentation is not limited to above mentioned best practices but involves other spheres like technical communication, tools and documentation process adopted in the company. I will discuss them in the next posts.