Posted by Some programmers spend most time documenting their code. The purpose of documentation is to leave helpful note for people who look at the code for the first time or later in a long time. Therefore, programmers need to document their code as articulate as possible to the readers. This article introduces five tips that would help me document my code at work, which are excerpted from Technical Writing One by Google.
- Use active voice
- Choose strong words over weak words
- Minimize certain adjectives and adverbs
- Know your audience
- Use lists
Use active voice
Use active voice most of time because of the following reasons:
- Active voice reports action directly whereas passive voice reports action indirectly.
- Active voice never drops an actor in a sentence, which passive voice does.
- Active voice is generally shorter than passive voice.
Choose strong words over weak words
Messages should be clear to the readers. Avoid words like happen and occur.
Bad sentence: The error happens when users click the submit button.
Good sentence: Clicking the submit button triggers the error.
Minimize certain adjectives and adverbs
Technical writing is not for the marketing purpose. Avoid words like seemingly, seamlessly, very, madly, nice, or anything that cannot be interpreted one way.
Bad sentence: Setting this flag makes the application run screamingly fast.
Good sentence: Setting this flag makes the application run 225-250% faster.
Know your audience
Determine the audience of documentation. It is because the audience’s knowledge will determine word usage and necessary information.
Examples of audience:
- software engineers
- technical, non-engineer roles (such as technical program managers)
- scientists
- professionals in scientific fields (for example, physicians)
- undergraduate engineering students
- graduate engineering students
- non-technical positions
Use lists
Use lists to organize information.
- Use a numbered list for ordered items.
- Use a bulleted list for unordered items
Thanks for reading.
Hope you enjoyed the article. If you have any question or opinion to share, feel free to write some comments.