Technical Documentation Writing Guidelines

Original link: https://sund.site/posts/technical-writing/

This article is excerpted from Part 1 of Technical Writing .

This article is suitable for readers who want to improve their technical document writing and daily communication skills in the technical field. It can also help to communicate in some business and non-literary English office scenarios.

Readers of this article can:

Improve the ability to communicate concepts and logic clearly, accurately and objectively in daily office work.
Master the English technical document writing standard.

Words

For an existing term, instead of reinventing a new term, use a link to a page that explains it.
If necessary, you can define new terms directly in the document, but if there are many terms, it is better to create a term comparison table.
Terms that appear throughout the document should have consistent names or abbreviations.
About abbreviations: For the first time, write the full name in bold and indicate the abbreviation in parentheses. Do not repeatedly mix the full name and abbreviation in subsequent articles. Correct example:

This document is for engineers who are new to the Telekinetic Tactile Network ( TTN ) or need to understand how to order TTN replacement parts through finger motions.
- If a term does not appear frequently, do not use abbreviations.
- Abbreviations are used when: 1. The abbreviation is significantly shorter; 2. The term occurs very frequently.
Use pronouns (It, they, that, etc.) sparingly.
- A pronoun must appear after the noun it refers to.
- If the pronoun is far from the noun it refers to (more than 5 words), don’t use the pronoun.
- The presence of a second noun between the noun and the pronoun creates ambiguity and should be avoided.

Analogy to computer programming languages:

Abbreviation = a level of abstraction for a term. The reader needs to spend more brainpower to expand it into the corresponding noun.

Pronoun = pointer. It is prone to ambiguity, so avoid causing “null pointer” errors in the reader’s mind.

Active voice

Active voice should be used whenever possible in technical documentation.
- Passive voice requires additional processing in the reader’s brain to be understood.
- The passive voice is used to express actions indirectly and can easily lead to confusion.
- Some passive voices omit the subject, forcing the reader to guess who the subject is.
If the passive voice is used, various forms of the past participle and prepositions (such as as, by) should be used correctly.
Imperative verbs (imperative verbs) should be in the active voice.
The passive voice (like It has been suggested that…) is often used in scientific papers, and it does not convey more information, and many scientific journals have begun to encourage the use of the active voice.

Clear sentences, Short sentences

Choose precise, powerful, specific verbs. Reduce imprecise, weak or generic verbs.
Bad examples: is, are, occur, happen

Be verbs and general verbs can be used, but they are often signs of bad writing habits, such as
- Missing action subject in sentence
- Sentence using passive voice
Reduce the there be sentence pattern, and extract the subject and verb in the there be sentence pattern, such as

Avoid this: There is no guarantee that the updates will be received in sequential order.
Should be changed to: Clients might not receive the updates in sequential order.
Use as few or no adjectives and adverbs as possible because these words are too subjective.
Use short sentences as much as possible. Short sentences are easier to read, easier to maintain, and less error-prone than long sentences.
- Each sentence expresses only one point of view.
- Convert long sentences into lists as much as possible.
- Use concise expressions and remove redundant words, such as
- Reduce clauses.
- Correctly distinguish between that and which clauses.

Lists and tables

Correctly distinguish between ordered lists (numbered lists) and unordered lists (bulleted lists).
Convert the items listed in the sentence (embedded list) into an unordered list, such as:
The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicugnas, and track dromedaries.
Replace it with:

The llamacatcher API enables callers to do the following:
- Create and query llamas.
- Analyze alpacas.
- Delete vicugnas.
- Track dromedaries.
Keep parallelism between list items (avoid mixing items from different levels in one column).
When using ordered lists, start with an imperative verb, such as:
Good example:
1. Download the Frambus app from Google Play or iTunes.
2. Configure the Frambus app’s settings.
3. Start the Frambus app.
Capitalization and periods are only used if each item in the list is a sentence, otherwise they are not.
Principles to follow when using the form:
- Each column has a header
- Keep the number of cells as small as possible
- Try to ensure that each column has the same data type
Before a table or list, use a sentence to introduce the context

Paragraphs

Start with a central sentence.
Write each paragraph around only one topic and do not include topic content that appears in other paragraphs.
Three to five sentences per paragraph, no more than seven sentences.
Paragraphs can explain three things: what, why, and how.

Audience

Good documentation = the knowledge and skills the reader needs to complete the task – the knowledge and skills the reader already has

Define who the audience is (developers, scientists, technical managers, undergrad engineering students, graduates, non-technical people…).
Find out how well the target readers have mastered different knowledge.
Determine what readers need and what they can learn from reading the documentation. For example, at the beginning of the design specification write:

After reading the design spec, the audience will learn the following: …
Satisfy readers:
- Explain necessary vocabulary and concepts.
- Friendly to newbies.
- Use simple English vocabulary.
- Be friendly to readers of different cultures and locales, and avoid using idioms or common sayings.

Documents

Declare the applicable scenarios (scope) of the document.
- It is best to declare which scenarios are not applicable (non-scope) and which readers are not suitable for reading. This is useful not only for readers, but also for writers to limit the scope of their writing.
Declare the target audience.
- It would be good to point out the knowledge and experience the reader should have before reading.
Summarize the key points of the document at the beginning
- By comparing and contrasting old ideas, readers can understand the new ideas you want to express.
Organize document formats according to readers’ needs.
A good outline:
1. Overview of the algorithm
  - Compare and contrast with quicksort, including Big O comparisons
    - Link to Wikipedia article on quicksort
  - Optimal datasets for the algorithm
2. Implementing the algorithm
  - Implementation in pseudocode
  - Implementation tips, including common mistakes
3. Deeper analysis of algorithm
  - Edge cases
  - Known unknowns

Punctuation

This part of the original text involves the usage of English punctuation marks, most of which are similar to Chinese rules, so they are omitted and not translated. Here is my experience with typography:

Where most Chinese people are prone to errors in English typography is the misuse of spaces. You can refer to this article: How to layout English punctuation? . In summary:
, ; : . ? ! These symbols are followed by a space
() '' "" Add spaces to the left and right of these paired symbols, and no spaces inside
/ - _ without spaces

Summarize

Consistent use of terminology.
Avoid ambiguous pronouns.
Active voice is better than passive voice.
Choose specific verbs instead of vague ones.
Each sentence focuses on an idea.
Turn some long sentences into lists.
Eliminate unnecessary words.
Use an ordered (number) list when there is order, and an unordered (dot) list when there is no order.
Keep list items parallel (same conceptual level).
Start ordered list items with imperative (mandatory) words.
Introduce lists and tables appropriately.
Begin by clarifying the central point of the paragraph.
Focus each paragraph on a topic.
Determine what your readers need to learn.
Adapt the document to the reader.
Point out key information at the beginning of the document.