Technical Writing Guidelines

  1. Never use the first-person collective (royal) pronouns, e.g., we/our, in technical documents.

    We prove lemma 1 using our result from theorem 2.

    The plural pronouns in this sentence refer to the writer (speaker) and reader (listener). However, only the writer proved lemma 1 and the result from theorem 2 only belongs to the writer; therefore, it is incorrect to include the reader. This style is particularly misleading when there is a single author describing individual work. All sentences of this form can be rewritten without pronouns:

    Lemma 1 is proved using the result from theorem 2.

    Do not replace first-person plural collective pronouns with the third-person singular generic human pronoun "one".

    One can see the proof for lemma 1 results from theorem 2.

    All sentences of this form can be rewritten without the pronoun:

    The proof for lemma 1 results from theorem 2.

  2. Clearly identify contributions, and do not be afraid to use the first-person singular (I/my) to accomplish this.

    I generalized Mulner's Banana-algorithm to include all tropical fruits.

    My patch for this problem is included in the Linux kernel.

    The following algorithm is new work but is based on Dicken's conjecture.

    If the reader cannot clearly differentiate prior work from new work, it is impossible to assess what has been accomplished.

  3. Do not use the future tense for physical references.

    The algorithm will be explained in Chapter 4.

    This sentence implies Chapter 4 is not written (temporal), when it is possible to go directly to Chapter 4 (physically) without waiting for the future. The sentence should read:

    The algorithm is explained in Chapter 4.

    The future tense should only be used when discussing actions that have not happened.

    I will attempt to extend algorithm 4 as part of my post-doctoral work.

    In general, use the present tense (is/are) in technical documents.

  4. Use the relative pronoun that to introduce a restrictive clause and which for a non-restrictive clause. A restrictive clause is defining and must appear to complete the thought of a sentence:

    A theory that has no proof is possible.

    The meaning of the sentence is trivial without the restrictive clause. A non-restrictive clause is parenthetical (optional) with respect to the thought of a sentence.

    A theory, which may or may not have a proof, is a systematic statement of rules or principles.

    The sentence is meaningful without the non-restrictive clause. A non-restrictive clause is always enclosed between commas.

  5. Use hyphens to connect adjectives that are dependent and to construct compound nouns. For example, the adjectives big, oval and red are independent and can be interchanged without altering the meaning of this sentence:

    The big oval red ball. The oval red big ball. The red big oval ball.

    However, interchanging is impossible when an adjective modifies another adjective and the noun is compound. For example, the adjectives real and time are dependent and the noun operating system is compound; hence, these words cannot be interchanged without changing the meaning of this sentence:

    The real time operating system failed. The time operating real system failed. The operating time real system failed.

    This sentence requires hyphens to bind together the adjectives and to construct the noun.

    The real-time operating-system failed.

  6. Use between and among properly. Between is used for exactly two; among is used for more than two.

    The money is divided between Jane and Tom.

    The money is divided among the five winners.

  7. Never use contractions in a technical document.

    I don't prove theorem 2 because I can't.

    Reserve contractions for narrative documents.

  8. Use an explicit noun rather than an implicit back-reference after the word "this", as in:

    Termites can eat the foundation of a house. This causes the house to fall down.

    The noun is the second sentence is implicitly something derived from the first sentence. It is better to be specific as to exactly what is being referenced, as in:

    Termites can eat the foundation of a house. This damage causes the house to fall down.

  9. While roadmaps are a common idiom in technical writing:

    Chapter 1 presents the background work. Chapter 2 introduces an idea and talks about it. Chapter 3 introduces another idea and discusses it in detail, including an implementation. A further idea is presented in Chapter 4 along with its implementation. The work is summed up and conclusions presented in Chapter 5, along with some future work.

    try to reduce or eliminate them at the end of the introduction and at the start of each section. In general, this information has little or no value, and is largely ignored by a reader.