Technical Writing
Research aiming to improve your technical documentation.
Last updated
Research aiming to improve your technical documentation.
Last updated
When writing or editing, learn to recognize terms that might be unfamiliar to some or all of your target audience. When you spot such a term, take one of the following two tactics:
If the term already exists, link to a good existing explanation.
If your document is introducing the term, define the term. If your document is introducing many terms, collect the definitions into a glossary.
Apply the same unambiguous word or term consistently throughout your document. Once you've named a component thingy, don't rename it thingamabob.
Namely, when introducing a long-winded concept name or product name, you may also specify a shortened version of that name. Then, you may use that shortened name throughout the document.
On the initial use of an unfamiliar acronym within a document or a section, spell out the full term, and then put the acronym in parentheses. Put both the spelled-out version and the acronym in boldface. You may then use the acronym going forward. Do not cycle back-and-forth between the acronym and the expanded version in the same document.
Here are the guidelines for acronyms:
Don't define acronyms that would only be used a few times.
Do define acronyms that meet both of the following criteria:
The acronym is significantly shorter than the full term.
The acronym appears many times in the document.
Consider the following pronoun guidelines:
Only use a pronoun after you've introduced the noun; never use the pronoun before you've introduced the noun.
Place the pronoun as close as possible to the referring noun. In general, if more than five words separate your noun from your pronoun, consider repeating the noun instead of using the pronoun.
If you introduce a second noun between your noun and your pronoun, reuse your noun instead of using a pronoun.
In an active voice sentence, an actor acts on a target. A passive voice sentence reverses the formula. Good sentences in technical documentation identify who is doing what to whom.
A passive verb consists of a form of "be" (is/are, was/were) plus a past participle verb (usually ending in -ed). In technical documentation, it's better to use active voice where an actor clearly performs an action on a target, rather than passive voice which reverses this formula.
Many technical writers believe that the verb is the most important part of a sentence. Pick the right verb and the rest of the sentence will take care of itself. Unfortunately, some writers reuse only a small set of mild verbs, which is like serving your guests stale crackers and soggy lettuce every day. Picking the right verb takes a little more time but produces more satisfying results.
Sentences that start with There is or There are marry a generic noun to a generic verb. Generic weddings bore readers. Show true love for your readers by providing a real subject and a real verb.
Adjectives and adverbs perform amazingly well in fiction and poetry. Thanks to adjectives, plain old grass becomes prodigal and verdant, while lifeless hair transforms into something lustrous and exuberant. Adverbs push horses to run madly and freely and dogs to bark loudly and ferociously. Unfortunately, adjectives and adverbs sometimes make technical readers bark loudly and ferociously. That's because adjectives and adverbs tend to be too loosely defined and subjective for technical readers. Worse, adjectives and adverbs can make technical documentation sound dangerously like marketing material.
Software engineers generally try to minimize the number of lines of code in an implementation for the following reasons:
Shorter code is typically easier for others to read.
Shorter code is typically easier to maintain than longer code.
Extra lines of code introduce additional points of failure.
In fact, the same rules apply to technical writing:
Shorter documentation reads faster than longer documentation.
Shorter documentation is typically easier to maintain than longer documentation.
Extra lines of documentation introduce additional points of failure.
Finding the shortest documentation implementation takes time but is ultimately worthwhile. Short sentences communicate more powerfully than long sentences, and short sentences are usually easier to understand than long sentences.
Focus each sentence on a single idea, thought, or concept. Just as statements in a program execute a single task, sentences should execute a single idea.
When you see the conjunction or in a long sentence, consider refactoring that sentence into a bulleted list. When you see an embedded list of items or tasks within a long sentence, consider refactoring that sentence into a bulleted or numbered list.
The following table suggests replacements for a few common bloated phrases:
at this point in time
now
determine the location of
find
is able to
can
A clause is an independent logical fragment of a sentence containing an actor and an action. Every sentence has a main clause and can have additional subordinate clauses, which modify the main idea but are less important. You can spot subordinate clauses by looking for introducing words like "which," "that," "because," "whose," "until," "unless," and "since."
That and which both introduce subordinate clauses. What's the difference between them? Well, in some countries, the two words are pretty much interchangeable. Inevitably though, alert readers from the United States will angrily announce that you confused the two words again.
In the United States, reserve which for nonessential subordinate clauses, and use that for an essential subordinate clause that the sentence can't live without.
Good lists can transform technical chaos into something orderly. Technical readers generally love lists. Therefore, when writing, seek opportunities to convert prose into lists.
The following types of lists dominate technical writing:
Bulleted lists
Numbered lists
Embedded lists
Use a bulleted list for unordered items; use a numbered list for ordered items. In other words:
If you rearrange the items in a bulleted list, the list's meaning does not change.
If you rearrange the items in a numbered list, the list's meaning changes.
An embedded list (sometimes called a run-in list) contains items stuffed within a sentence. Generally speaking, embedded lists are a poor way to present technical information. Try to transform embedded lists into either bulleted lists or numbered lists.
Effective lists are parallel; defective lists tend to be nonparallel. All items in a parallel list look like they "belong" together. That is, all items in a parallel list match along the following parameters:
Grammar
Logical category
Capitalization
Punctuation
Conversely, at least one item in a nonparallel list fails at least one of the preceding consistency checks.
Consider starting all items in a numbered list with an imperative verb. An imperative verb is a command, such as open or start. For example, notice how all of the items in the following parallel numbered list begin with an imperative verb:
Download the Frambus app from Google Play or iTunes.
Configure the Frambus app's settings.
Start the Frambus app.
Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes zoom towards the table.
Consider the following guidelines when creating tables:
Label each column with a meaningful header. Don't make readers guess what each column holds.
Avoid putting too much text into a table cell. If a table cell holds more than two sentences, ask yourself whether that information belongs in some other format.
Although different columns can hold different types of data, strive for parallelism within individual columns. For instance, the cells within a particular table column should not be a mixture of numerical data and famous circus performers.
We recommend introducing each list and table with a sentence that tells readers what the list or table represents. In other words, give the list or table context. Terminate the introductory sentence with a colon rather than a period.
Although not a requirement, we recommend putting the word following into the introductory sentence
The work of writing is simply this: untangling the dependencies among the parts of a topic, and presenting those parts in a logical stream that enables the reader to understand you.
The opening sentence is the most important sentence of any paragraph. Busy readers focus on opening sentences and sometimes skip over subsequent sentences. Therefore, focus your writing energy on opening sentences. Good opening sentences establish the paragraph's central point.
A paragraph should represent an independent unit of logic. Restrict each paragraph to the current topic. Don't describe what will happen in a future topic or what happened in a past topic. When revising, ruthlessly delete (or move to another paragraph) any sentence that doesn't directly relate to the current topic.
Long paragraphs are visually intimidating. Very long paragraphs form a dreaded "wall of text" that readers ignore. Readers generally welcome paragraphs containing three to five sentences, but will avoid paragraphs containing more than about seven sentences. When revising, consider dividing very long paragraphs into two separate paragraphs.
Conversely, don't make paragraphs too short. If your document contains plenty of one-sentence paragraphs, your organization is faulty. Seek ways to combine those one-sentence paragraphs into cohesive multi-sentence paragraphs or possibly into lists.
Good paragraphs answer the following three questions:
What are you trying to tell your reader?
Why is it important for the reader to know this?
How should the reader use this knowledge? Alternatively, how should the reader know your point to be true?
To define your audience effectively, start by identifying their roles - whether they are software engineers, technical program managers, scientists, medical professionals, students, or non-technical staff. However, roles alone aren't enough to understand your audience fully.
Consider both your audience's familiarity with the subject matter and how recently they've used relevant knowledge. For example, while software engineers may have studied advanced math, those skills fade if unused in their daily work. Similarly, experience level matters - veteran team members typically understand project details better than newcomers.
Write down a list of everything your target audience needs to learn to accomplish goals. In some cases, the list should hold tasks that the target audience needs to perform.
Note that your audience must sometimes master tasks in a certain order. If you are writing a design spec, then your list should focus on information your target audience should learn rather than on mastering specific tasks
Writing to meet your audience's needs requires unselfish empathy. You must create explanations that satisfy your audience's curiosity rather than your own. How do you step out of yourself in order to fit documentation to the audience? Unfortunately, we can offer no easy answers. We can, however, offer a few parameters to focus on.
Match your vocabulary to your audience.
Experts often suffer from the curse of knowledge, which means that their expert understanding of a topic ruins their explanations to newcomers.
Prefer simple overs over complex words.
Keep your writing culturally neutral. Do not require readers to understand the intricacies of NASCAR, cricket, or sumo in order to understand how a piece of software works.
A good document begins by defining its scope. A better document additionally defines its non-scope — the topics not covered that the target audience might reasonably expect your document to cover.
Scope and non-scope statements benefit not only the reader but also the writer. While writing, if the contents of your document veer away from the scope statement (or venture into the non-scope statement), then you must either refocus your document or modify your scope statement. When reviewing your first draft, delete any sections that don't help satisfy the scope statement.
A good document explicitly specifies its audience. Beyond the audience's role, a good audience declaration might also specify any prerequisite knowledge or experience.
In some cases, the audience declaration should also specify prerequisite reading or coursework.
Engineers and scientists are busy people who won't necessarily read all 76 pages of your design document. Imagine that your peers might only read the first paragraph of your document. Therefore, ensure that the start of your document answers your readers' essential questions.
To create effective documentation, start by understanding your audience's needs. Consider who they are, what goals they want to achieve, and their existing knowledge level. Most importantly, determine what new knowledge or skills readers should gain from your document. These questions will help shape your content to be truly useful for your readers.
Once you have a clear picture of your audience's needs, carefully organize your document to serve those needs effectively. Structure the information in a logical flow that guides readers from their current understanding to the knowledge they need to acquire. This thoughtful organization ensures readers can easily find and absorb the information they're looking for.
In English, the rules regarding commas are somewhat hazier. As a guideline, insert a comma wherever a reader would naturally pause within a sentence. While some situations require a comma, others are more flexible. For example, the serial comma (or Oxford comma) between the last two items in a list is controversial, though we recommend using it to avoid ambiguity in technical writing. Additionally, always place a comma between a condition and its consequence in conditional sentences, but avoid using commas to incorrectly join independent thoughts.
A period separates distinct thoughts, while a semicolon unites highly related thoughts that are each complete sentences. Before using a semicolon, ensure both parts could stand alone and consider if the sentence would still make sense if you flipped the thoughts to opposite sides. In most cases, especially for embedded lists, you should use commas rather than semicolons to separate items.
Em dashes are compelling punctuation marks, rich with punctuation possibilities. An em dash represents a longer pause—a bigger break—than a comma. Consider the horizontal punctuation marks shown in the following table:
em dash
—
widest (usually, the length of the letter m)
en dash
–
medium (usually, the length of the letter n)
hyphen
-
narrowest
Use parentheses to hold minor points and digressions. Parentheses inform readers that the enclosed text isn't critical. Because the enclosed text isn't critical, some editors feel that text that deserves parentheses doesn't deserve to be in the document. As a compromise, keep parentheses to a minimum in technical writing.
The rules regarding periods and parentheses aren't always clear. Here are the standard rules:
If a pair of parentheses holds an entire sentence, the period goes inside the closing parenthesis.
If a pair of parentheses ends a sentence but does not hold the entire sentence, the period goes just outside the closing parenthesis.
Though different style guides offer conflicting advice about punctuating list items, the recommends (with some exceptions) starting each list item with a capital letter. If a list item is a sentence, use appropriate sentence-ending punctuation.
In technical writing, use a colon to alert readers that a list or table will follow. In other words, terminate the with a colon. Technical writing prefers bulleted lists or numbered lists to embedded lists. That said, you can use a colon to introduce an embedded list.