Technical Documentation Tips

Accept that, documentation often is a burden for developers. On the other hand, it is one of the most important parts in many aspects. In this post, I will try to show these aspects with real examples. These tips can be applied to documents(docs) that are prepared for developers, scrum masters, or product owners mainly, not for customers. After this post, you will be able to write more effective docs.

Photo by Nicolas Thomas on Unsplash

There are no sharp rules for writing a good doc but some rule sets can be used. In that sense, we are based on the Google way but of course with some additional differences.

Pros

• New developers can easily explore the existing processes
• Existing developers can find the information on what they are looking for
• If a topic is known by only one person, documentation would reduce this dependency
• The author can reinforce the subject that he/she writes.

Cons

• Usually, developers don’t like writing docs
• Docs always need to be kept up to date

Let’s talk about tips!

Good Doc

# The author should provide answers to these questions for a good doc

• Who is the target audience?
• What do the readers assume to know before reading the doc?
• What will the readers learn from the doc after reading it?

# Good doc begins with its scope

If the readers know the scope of the document upfront, they can put more attention into reading or even decide to stop reading.

# Illustrations would be beneficial

Illustrations, gifs, or animations are mostly welcome by readers. It helps the information secure its place in the reader’s mind permanently.

Words

# Unfamiliar or new terms

Unknown terms can be quite distractive. We have to be careful not to leave any undefined terms.

• If a term is already defined in another doc, link to it.

• If not, the term has to be defined. If there are a lot of terms that need definition, they can be listed as a glossary below the doc.

# Acronyms

• We should spell out the full term before using the acronym version.

• An acronym should be used if it is worthy to use. For example, if it is used only one time, it would be confusing.
• Some acronyms no need to spelled out upfront depends on the target readers. In our case, developers already know HTML, REST, Saas, etc.

# Pronouns

Pronouns refer to the previous noun. Improper use of pronouns can be confusing.

• Put the pronoun as close as possible to the noun. A maximum of five words can be allowed between them. Here is a good example of bad usage.

• Otherwise reuse the noun again. It would be a good solution for the case above; … the simulator will provide …

Active Voice

Using active voice is the clearest way to explain something in docs. Most readers try to convert passive voice to active voice. Or they try to guess the subject while reading it. Therefore, we must keep the doc simple as possible and use active voice.

Clear Sentences

# Find a strong verb

• Finding the proper verb can take more time but it produces more effective results.
• Avoid using common and weak verbs, such as, happen, occur, am/is/are, there are/is. Google gives us good samples;

# Convert long sentences to list

According to our keep simple as possible principle, long sentences are not our friend. They are making it difficult to understand the topic. Splitting the sentence into small pieces and turning it into a list would be a good way to improve clarity.

# Don’t use idioms

Idioms are very important in every culture but in an international domain, it would be hard to understand.

List and Tables

Analytic minds tend to like visual data. Hence, lists and tables are important points in technical docs.

# Lists

• Use bullet lists for unordered items
• Use numbered list for ordered items
• Numbered items should start with imperative words

# Tables

• Avoid putting too much data in a cell. Nevertheless, if you have to put too much data, probably you must split the current column into new columns.
• The table always has to be introduced.

Code Samples

A clean code sample can impress developers more than words. Moreover, despite all the good documentation, a developer would rather see a code sample.

• Code sample have to be without error
• Details can skip with some explanatory comments, only important parts should be highlighted
• Code samples need to be up to date.

I hope you’ve found this article helpful. If you have any questions or remarks don’t hesitate to leave a comment!

References

• https://developers.google.com/tech-writing
• https://beam.apache.org/documentation/