1 Writing technical documentation #
Technical writing has certain characteristics that make it different from other types of writing. Its objective is to provide readers with complex information and comprehensive answers they are searching for. The content should be well-structured, clear and concise. Effective technical documentation is straightforward, detailed and focused on problem-solving, and there is a specific workflow for its creation:
- Defining the target audience
Adjust tone, style and technicality of the text based on the intended audience. Keep in mind that not all facts that seem obvious to you will be obvious to your readers.
- Researching a topic
Start with research on the information that is relevant to the target audience. Receive essential input from issue tracking systems like GitHub, and project management tools.
- Writing about a topic
Start writing at an early stage, even if you have not finished your research yet. Prepare a draft document and discuss it with subject-matter experts.
- Getting reviews
In a first review of your text, identify and fix the most obvious issues like typos, unfinished sentences, etc. After self-review, ask for a technical review by dedicated specialists. A technical review uncovers technical or factual errors like missing or misspelled package names, wrong commands or forgotten options.
Request a peer review which can improve your text and detect any structural problems or logical traps. You can then do a spell check, link check and style check with the DAPS tool.
Finally, ask for a linguistic review that tackles language issues, typos, inconsistencies, and style guide compliance.
For more information on how to produce meaningful content that will rank high on the Web, see Chapter 5, Writing for the Web and Section 5.2, “Writing SEO-friendly content”.