Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / SUSE Documentation Style Guide / Writing technical documentation
Applies to 2024-07

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”.