Keith Johnson concluded the last session of the Technical Writing Project Lifecycle workshop organized by Advanced Technical Writing Group in association with Metapercept Technology Services and Oxygen XML with insights into micro technical writing. He explained the steps to follow after completing the macro technical writing process. These steps ensure effective and efficient completion of the technical documentation project once you are ready to write the document.

Technical writing holds immense importance as it communicates a technology or process to its end-users. The magnitude of its impact is crucial for the organization as well as its users. Therefore, Keith shares the following steps that would help any technical writer to succeed in their career.

1.      Objective:

You must start by laying down the objective of the document. It should set the right expectations by stating facts such as the scope of the document, prerequisites to perform tasks, etc. It should give a clearer picture to the readers about how the document will be useful for them. This can be done by working with the tech lead, scrum master, etc.

2.      Tactics:

You must follow a conversational and simple tone for engaging with the readers. The more the readability of the document, the better will be the user experience. Apart from following the style guide suggested by the organization, you should follow the tactics mentioned below for writing effective technical documents:

• Use present tense. It increases the ease of using the document by eliminating room for ambiguity.
• Use ‘you’ instead of ‘user’. It helps in engaging your readers.
• Keep your sentences short and concise. If you use longer sentences, the reader might get confused or lost midway.
• The paragraphs should not contain more than five sentences. In fact, three to four sentences are better to help the reader comprehend easily.
• There should be a balance between your text and images. Too much text or images can confuse the readers. If possible, Keith suggests it should be an optimal balance of 50-50%.
• Do not overwhelm readers with more than three concepts per screenshot.
• Ensure to add margins on the top, bottom, and the sides as writing towards the edges might end up snipping content in the final output. A margin of 1 inch is the best option if no guidelines are provided.
• If there isn’t any font size and style recommended for the document, you should choose Calibri 12. It has a good universal renderability for different screen sizes.
• You should add a table of contents, index, glossary, headings, etc. It increases the ease of navigation and provides enough information to readers for easy understanding.
• Lastly, make sure you understand what you are writing. You should be able to walk in your reader’s shoes and understand the context from their perspective. If you do not understand what you are documenting, you might end up leaving information gaps in the document.

3.      Outline:

At this point, before you start adding content to the document, prepare a flow chart or a diagram that represents the structure of the document. You can afford to spare the details and focus on the outline only. This diagram will serve as the ‘documentation roadmap’ and you can specify small milestones.

4.      Content:

It is in this phase that you start developing the document by adding content. As mentioned above, technical documentation helps the end-users to use a technology or a product. It helps the users to understand processes and perform tasks. Therefore, it is imperative for technical writers to not rush the writing process. Imagine the reader watching you over as you write and compose your document.

5.      Edit and proofread:

Editing and proofreading are entirely different from each other. While editing takes care of the language, grammar, etc., proofreading ensures the technical correctness of the information offered. For technical accuracy, you can reach out to SMEs again. For editorial review, you can refer to style guides to ensure consistency throughout the document.

6.      Sign off:

This is where your document is officially ready for consumption by the intended audience. Every company has different protocols for signing off. Ensure that the document meets business and technical goals. Then, you can complete the required protocols and get them documented before releasing the final document.

7.      Deploy:

Companies use different platforms such as Google Drive, One Drive, Confluence, etc. for document repositories. Check with your manager where the document should reside in its final form. Also, it is advised to keep the document in its original word/PDF format too. Then, before closing the project, touch base with documentation admins to ensure that you have fulfilled all the protocols.

Conclusion

Based on your understanding, the reader will also understand the process or product, or technology. Therefore, you need to focus on all the granularities of the technical documentation project. Further, you must also focus on building a good user experience for the readers by enhancing the readability of the document.

Both macro and micro technical writing are crucial for you to become an effective technical writer. One can’t afford to skip any of the steps shared by Keith. For this purpose, as a contribution to the technical writing community, he has shared the following roadmap that covers both macro and micro technical writing aspects:

If you are an aspiring technical writer or have any technical documentation requirements, contact us; or you can explore our services!

Author: Ruchi Rai, Technical Writer, Metapercept Technology Services LLP