Estimated Time: 15 minutes
The vast majority of sentences in technical writing should be in active voice. This unit teaches you how to do the following:
- Distinguish passive voice from active voice.
- Convert passive voice to active voice because active voice is usually clearer.
First, watch this video, just to get the ball rolling[^1]:
In an active voice sentence, an actor acts on a target. That is, an active voice sentence follows this formula:
Active Voice Sentence = actor + verb + target
A passive voice sentence reverses the formula. That is, a passive voice sentence typically follows the following formula:
Passive Voice Sentence = target + verb + actor
For example, here’s a short, active voice sentence:
The cat sat on the mat.
- Actor: The cat
- Verb: sat
- Target: the mat
By contrast, here's that same sentence in passive voice:
The mat was sat on by the cat.
- Target: The mat
- Passive verb: was sat
- Actor: the cat
Some passive voice sentences omit an actor. For example:
The mat was sat on.
- Actor: unknown
- Passive verb: was sat
- Target: the mat Who or what sat on the mat? A cat? A dog? A T-Rex? Readers can only guess. Good sentences in technical documentation identify who is doing what to whom.
Passive verbs typically have the following formula:
passive verb = form of be + past participle verb
Although the preceding formula looks daunting, it is actually pretty simple:
A form of be in a passive verb is typically one of the following words:
- is/are
- was/were
A past participle verb is typically a plain verb plus the suffix ed. For example, the following are past participle verbs:
- interpreted
- generated
- formed
Unfortunately, some past participle verbs are irregular; that is, the past participle form doesn't end with the suffix ed. For example:
- sat
- known
- frozen
Putting the form of be and the past participle together yields passive verbs, such as the following:
- was interpreted
- is generated
- was formed
- is frozen
If the phrase contains an actor, a preposition ordinarily follows the passive verb. (That preposition is often a key clue to help you spot passive voice.) The following examples combine the passive verb and the preposition:
- was interpreted as
- is generated by
- was formed by
- is frozen by
It is easy to mistakenly classify sentences starting with an imperative verb as passive. An imperative verb is a command. Many items in numbered lists start with imperative verbs. For example, Open and Set in the following list are both imperative verbs:
- Open the configuration file.
- Set the Frombus variable to False.
Sentences that start with an imperative verb are typically in active voice, even though they don't explicitly mention an actor. Instead, sentences that start with an imperative verb imply an actor. The implied actor is you.
Mark each of the following sentences as either Passive or Active:
- MutableInput provides read-only access.
- Read-only access is provided by MutableInput.
- Performance was measured.
- Python was invented by Guido van Rossum in the twentieth century.
- David Korn discovered the KornShell quite by accident.
- This information is used by the policy enforcement team.
- Click the Submit button.
- The orbit was calculated by Katherine Johnson.
Click to see the answer
- Active. MutableInput provides read-only access.
- Passive. Read-only access is provided by MutableInput.
- Passive. Performance was measured.
- Passive. Python was invented by Guido van Rossum in the twentieth century.
- Active. David Korn discovered the KornShell quite by accident.
- Passive. This information is used by the policy enforcement team.
- Active. Click the Submit button. (Click is an imperative verb.)
- Passive. The orbit was calculated by Katherine Johnson.
Many sentences contain multiple verbs, some of which are active and some of which are passive. For example, the following sentence contains two verbs, both of which are in passive
contains two verbs, both of which are in passive voice:
Here is that same sentence, partially converted to active voice:
add_circle And here is that same sentence, now fully converted to active voice:
Exercise
Each of the following sentences contains two verbs. Categorize each of the verbs in the following sentences as either active or passive.
For example, if the rst verb is active and the second is passive, write Active, Passive.
1. The QA team loves ice cream, but the writers prefer sorbet.
2. Performance metrics are required by the team, though I prefer wild guesses.
3. When software engineers attempt something new and innovative, a reward should be given.
Click the icon to see the answer.
1. Active, Active. The QA team loves ice cream, but the writers prefer sorbet.
2. Passive, Active. Performance metrics are required by the team, though I prefer wild guesses.
3. Active, Passive. When software engineers attempt something new and innovative, a reward should be given.
Prefer active voice to passive voice
Use the active voice most of the time. Use the passive voice sparingly. Active voice provides the following advantages:
Most readers mentally convert passive voice to active voice. Why subject your readers to extra processing time? By sticking to active
voice, you enable readers to skip the preprocessor stage and go straight to compilation.
Passive voice obfuscates your ideas, turning sentences on their head. Passive voice reports action indirectly.
Some passive voice sentences omit an actor altogether, which forces the reader to guess the actor's identity.
Active voice is generally shorter than passive voice.
Be bold—be active.
Scienti c research reports (optional material)
Passive voice runs rampant through certain scienti c research reports. In those research reports, experimenters and their equipment
often disappear, leading to passive sentences that start off as follows:
It has been suggested that...
Data was taken...
Statistics were calculated...
Results were evaluated.
Do we know who is doing what to whom? No. Does the passive voice somehow make the information more objective? No.
Many scienti c journals have embraced active voice. We encourage the remainder to join the quest for clarity.
add_circle Exercise Rewrite the following passive voice sentences as active voice. Only part of certain sentences are in passive voice; ensure that all parts end
up as active voice:
1. The ags weren't parsed by the Mungi er.
2. A wrapper is generated by the Op registration process.
3. Only one experiment per layer is selected by the Frombus system.
4. Quality metrics are identi ed by asterisks; ampersands identify bad metrics.
Click the icon to see the answer.
1. The Mungi er didn't parse the ags.
2. The Op registration process generates a wrapper.
3. The Frombus system selects only one experiment per layer.
4. Asterisks identify quality metrics; ampersands identify bad metrics.
Next unit: Clear sentences (/tech-writing/one/clear-sentences)
1. "Get the ball rolling" is an idiom that means "to get something started." ↩ (#ref1)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/) ,
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0) . For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies) . Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC.
add_circle Audience Estimated Time: 10 minutes
The course designers believe that you are probably comfortable with mathematics. Therefore, this unit begins with an equation:
good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills
In other words, make sure your document provides the information that your audience needs but doesn't already have. Therefore, this unit
explains how to do the following:
De ne your audience.
Determine what your audience needs to learn.
Fit documentation to your audience.
As the following video suggests, targeting the wrong audience can be messy:
De ne your audience Serious documentation efforts spend considerable time and energy on
de ning their audience. These efforts might involve surveys, user
experience studies, focus groups, and documentation testing. You
probably don't have that much time, so this unit takes a simpler
approach.
Begin by identifying your audience's role(s). Sample roles include:
Software engineers
Technical, non-engineer roles (such as technical program managers)
Scientists
Professionals in scienti c elds (for example, physicians)
Undergraduate engineering students
Graduate engineering students
Non-technical positions
We happily appreciate that many people in non-technical roles have great technical and mathematical skills. However, roles remain an
essential rst-order approximation in de ning your audience. People within the same role generally share certain base skills and
knowledge. For example:
Most software engineers know popular sorting algorithms, big O notation (https://en.wikipedia.org/wiki/Big_O_notation), and at least one
programming language. Therefore, you can depend on software engineers knowing what O(n) means, but you can't depend on non-
technical roles knowing O(n).
A research report targeted at physicians should look very different from a newspaper article about the same research aimed at a lay
audience.
A professor's explanation of a new machine learning approach to graduate students should differ from the explanation to rst-year
undergraduate students.
Writing would be so much easier if everyone in the same role shared exactly the same knowledge. Unfortunately, knowledge within the
same role quickly diverges. Amal is an expert in Python, Sharon's expertise is C++, and Micah's is in Java. Kara loves Linux, but David only
knows iOS.
Roles, by themselves, are insu cient for de ning an audience. That is, you must also consider your audience's proximity to the knowledge.
The software engineers in Project Frombus know something about related Project Dingus but nothing about unrelated Project Carambola.
The average heart specialist knows more about ear problems than the average software engineer but far less than an audiologist. Time also affects proximity. Almost all software engineers, for example, studied calculus. However, most software engineers don't use
calculus in their jobs, so their knowledge of calculus gradually fades. Conversely, experienced engineers typically know vastly more about
their current project than new engineers on the same project.
Sample audience analysis The following is a sample audience analysis for ctitious Project Zylmon:
The target audience for Project Zylmon falls into the following roles:
Software engineers
Technical product managers
The target audience has the following proximity to the knowledge:
My target audience already knows the Zyljeune APIs, which are somewhat similar to the Zylmon APIs.
My target audience knows C++, but has not typically built C++ programs in the new Winged Victory development environment.
My target audience took linear algebra in university, but many members of the team need a refresher on matrix multiplication.
Determine what your audience needs to learn 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. For example:
After reading the documentation, the audience will know how to do the following tasks:
Use the Zylmon API to list hotels by price.
Use the Zylmon API to list hotels by location.
Use the Zylmon API to list hotels by user ratings.
Note that your audience must sometimes master tasks in a certain order. For example, your audience might need to learn how to build and
execute programs in a new development environment before learning how to write particular kinds of programs.
If you are writing a design spec, then your list should focus on information your target audience should learn rather than on mastering
speci c tasks. For example:
After reading the design spec, the audience will learn the following:
Three reasons why Zylmon outperforms Zyljeune.
Five reasons why Zylmon consumed 5.25 engineering years to develop.
Fit documentation to your audience Writing to meet your audience's needs requires unsel sh 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 t documentation to the audience? Unfortunately, we can offer no easy
answers. We can, however, offer a few parameters to focus on.
Vocabulary and concepts Match your vocabulary to your audience. See Words (/tech-writing/one/words) for help. Be mindful of proximity. The people on your team probably understand your team's abbreviations, but do people on other teams
understand those same abbreviations? As your target audience widens, assume that you must explain more.
Similarly, experienced people on your software team probably understand the implementation details and data structures of your team's
project, but nearly everyone else (including new members of your team) does not. Unless you are writing speci cally for other experienced
members of your team, you typically must explain more than you expect.
Curse of knowledge
Experts often suffer from the curse of knowledge, which means that their expert understanding of a topic ruins their explanations to
newcomers. As experts, it is easy to forget that novices don’t know what you already know. Novices might not understand explanations
that make passing reference to subtle interactions and deep systems that the expert doesn’t stop to explain.
From the novice's point of view, the curse of knowledge is a "File not found" linker error due to a module not yet compiled.
Exercise
1. Assume that the following paragraph is the start of a paper aimed at physicians who have never programmed before. Identify the
aspects of the paragraph that suffer from the curse of knowledge:
C is a mid-level language, higher than assembly language but lower than Python and Java. The C language provides programmers
ne-grained control over all aspects of a program. For example, using the C Standard Library, it is easy to allocate and free blocks
of memory. In C, manipulating pointers directly is mundane.
2. Suppose the preceding paragraph was aimed at undergraduate computer science students new to C but comfortable with Python.
Does the paragraph still suffer from the curse of knowledge?
Click the icon to see the answer.
1. This paragraph suffers immensely from the curse of knowledge. The target audience has never programmed before, so the following
terms are inappropriate or unfamiliar:
Language
Mid-level language
Assembly language
Python
Java
Program
C Standard Library
Allocate and free blocks of memory
Pointers
2. This paragraph also suffers from the curse of knowledge for the alternative audience. The average Python programmer is unaware
of manipulating memory or pointers. A better introductory paragraph would compare and contrast C with Python.
Simple words
English has become the dominant language for technical communication worldwide. However, a signi cant percentage of technical
readers are more comfortable in languages other than English. Therefore, prefer simple words over complex words; avoid obsolete or
overly-complex English words. Sesquipedalian (https://www.google.com/search?q=sesquipedalian) and rare words repel some readers.
Cultural neutrality and idioms
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. For example, the following sentence—packed with baseball metaphors as American as apple
pie—might puzzle some Parisian readers:
add_circle If Frambus 5.0 was a solid single, Frambus 6.0 is a stand-up double.
Idioms are phrases whose overall meaning differs from the literal meaning of the individual words in that phrase. For example, the
following phrases are idioms:
a piece of cake
Bob's your uncle
Cake? Bob? Most readers from the United States recognize the rst idiom; most British readers recognize the second idiom. If you are
writing strictly for a British audience, then Bob's your uncle can be ne. However, if you are writing for an international audience, then
replace that idiom with this task is done.
Idioms are so deeply ingrained in our speech that the special nonliteral meaning of idioms becomes invisible to us. That is, idioms are
another form of the curse of knowledge.
Note that some people in your audience use translation software to read your documentation. Translation software tends to struggle more
with cultural references and idioms than with plain, simple English.
Exercise
Identify the problems with the following sentences:
1. As of Version 3.0, it was still kosher to call the Frambus method.
2. Deciding which BlogResource constraints are combinable is a sticky wicket.
3. Be that as it may, you still have to write unit tests.
Click the icon to see the answer.
1. In some places in the world, kosher has become slang for "acceptable usage." Many readers, however, will wonder how religious
dietary laws pertain to software.
2. A sticky wicket is British slang, which does not travel well. Substituting the phrase challenging problem will x this issue.
3. Be that as it may is an idiom. Substituting the transition However will x this problem.
Next unit: Documents (/tech-writing/one/documents)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC.
add_circle Clear sentences Estimated Time: 10 minutes
Comedy writers seek the funniest results, horror writers strive for the scariest, and technical writers aim for the clearest. In technical
writing, clarity takes precedence over all other rules. This unit suggests a few ways to make your sentences beautifully clear.
Choose strong verbs
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.
To engage and educate readers, choose precise, strong, speci c verbs. Reduce imprecise, weak, or generic verbs, such as the following:
Forms of be: is, are, am, was, were, etc.
Occur
Happen
For example, consider how strengthening the weak verb in the following sentences ignites a more engaging sentence:
Weak Verb Strong Verb
The exception occurs when dividing by zero. Dividing by zero raises the exception.
This error message happens when... The system generates this error message when...
We are very careful to ensure... We carefully ensure...
Many writers rely on forms of be as if they were the only spices on the rack. Sprinkle in different verbs and watch your prose become more
appetizing. That said, a form of be is sometimes the best choice of verb, so don't feel that you have to eliminate every form of be from your
writing.
Note that generic verbs often signal other ailments, such as:
An imprecise or missing actor in a sentence
A passive voice sentence
Exercise
Clarify the following sentences by picking more speci c verbs. Along the way, feel free to rearrange the sentences and to add, modify, or
delete words:
1. When a variable declaration doesn't have a datatype, a compiler error happens.
2. Compiler errors occur when you leave off a semicolon at the end of a statement.
Click the icon to see the answer.
1. A few possible answers:
When a variable declaration doesn't specify a datatype, the compiler generates an error message.
If you declare a variable but don't specify a datatype, the compiler generates an error message.
2. A few possible answers:
Compilers issue errors when you omit a semicolon at the end of a statement.
A missing semicolon at the end of a statement triggers compiler errors.
add_circle Reduce there is / there are 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.
In the best-case scenario, you may simply delete There is or There are (and possibly another word or two later in the sentence). For
example, consider the following sentence:
There is a variable called met_trick that stores the current accuracy.
Removing There is replaces the generic subject with a better subject. For example, either of the following sentences is clearer than the
original:
A variable named met_trick stores the current accuracy.
The met_trick variable stores the current accuracy.
You can sometimes repair a There is or There are sentence by moving the true subject and true verb from the end of the sentence to the
beginning. For example, notice that the pronoun you appears towards the end of the following sentence:
There are two disturbing facts about Perl you should know.
Replacing There are with You strengthens the sentence:
You should know two disturbing facts about Perl.
In other situations, writers start sentences with There is or There are to avoid the hassle of creating true subjects or verbs. If no subject
exists, consider creating one. For example, the following There is sentence does not identify the receiving entity:
There is no guarantee that the updates will be received in sequential order.
Replacing "There is" with a meaningful subject (such as clients) creates a clearer experience for the reader:
Clients might not receive the updates in sequential order.
Exercise
Clarify the following sentences by removing There is, and possibly rearranging, adding, modifying, or deleting other words:
1. There is a lot of overlap between X and Y.
2. There is no creator stack for the main thread.
3. There is a low-level, TensorFlow, Python interface to load a saved model.
4. There is a sharding function named distribute that assigns keys.
Click the icon to see a possible answer.
1. X and Y overlap a lot.
2. The main thread does not provide a creator stack.
3. TensorFlow provides a low-level Python interface to load a saved model.
4. The distribute sharding function assigns keys.
Minimize certain adjectives and adverbs (optional)
add_circle Adjectives and adverbs perform amazingly well in ction 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 de ned and subjective for technical readers. Worse, adjectives and adverbs can
make technical documentation sound dangerously like marketing material. For example, consider the following passage from a technical
document:
Setting this ag makes the application run screamingly fast.
Granted, screamingly fast gets readers' attention but not necessarily in a good way. Feed your technical readers factual data instead of
marketing speak. Refactor amorphous adverbs and adjectives into objective numerical information. For example:
Setting this ag makes the application run 225-250% faster.
Does the preceding change strip the sentence of some of its charm? Yes, a little, but the revamped sentence gains accuracy and
credibility.
Note: Don't confuse educating your readers (technical writing) with publicizing or selling a product (marketing writing). When your readers expect education,
provide education; don't intersperse publicity or sales material inside educational material.
Next unit: Short sentences (/tech-writing/one/short-sentences)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Creating sample code Estimated Time: 10 minutes
Good sample code is often the best documentation. Even if your paragraphs and lists are as clear as blue water, programmers still prefer
good sample code. After all, text and code are different languages, and it is code that the reader ultimately cares about. Trying to describe
code with text is like trying to explain an Italian poem in English.
Good samples are correct and concise code that your readers can quickly understand and easily reuse with minimal side effects.
Correct Sample code should meet the following criteria:
Build without errors.
Perform the task it claims to perform.
Be as production-ready as possible. For example, the code shouldn't contain any security vulnerabilities.
Follow language-speci c conventions.
Sample code is an opportunity to directly in uence how your users write code. Therefore, sample code should set the best way to use your
product. If there is more than one way to code the task, code it in the manner that your team has decided is best. If your team hasn't
considered the pros and cons of each approach, take time to do so.
Always test your sample code. Over time, systems change and your sample code may break. Be prepared to test and maintain sample
code as you would any other code.
Many teams reuse their unit tests as sample programs, which is sometimes a bad idea. The primary goal of a unit test is to test; the only
goal of a sample program is to educate.
A snippet is a piece of a sample program, possibly only one or a few lines long. Snippet-heavy documentation often degrades over time
because teams tend not to test snippets as rigorously as full sample programs.
Running sample code Good documents explain how to run sample code. For example, your document might need to tell users to perform activities such as the
following prior to running the samples:
Install a certain library.
Adjust the values assigned to certain environment variables.
Adjust something in the integrated development environment (IDE).
Users don't always perform the preceding activities properly. In some situations, users prefer to run or (experiment with) sample code
directly in the documentation. ("Click here to run this code.")
Writers should consider describing the expected output or result of sample code, especially for sample code that is di cult to run.
Concise Sample code should be short, including only essential components. When a novice C programmer wants to learn how to call the malloc function, give that programmer a brief snippet, not the entire Linux source tree. Irrelevant code can distract and confuse your audience.
That said, never use bad practices to shorten your code; always prefer correctness over conciseness.
Understandable Follow these recommendations to create clear sample code:
Pick descriptive class, method, and variable names.
Avoid confusing your readers with hard-to-decipher programming tricks.
Avoid deeply nested code.
Optional: Use bold or colored font to draw the reader's attention to a speci c section of your sample code. However, use highlighting
judiciously—too much highlighting means the reader won't focus on anything in particular.
Exercise
Which of the following would be a more helpful line of code in a sample program? Assume that the target audience consists of software
engineers new to the go.so API.
1. MyLevel = go.so.Level(5, 28, 48)
2. MyLevel = go.so.Level(rank=5, 28, 48)
3. MyLevel = go.so.Level(rank=5, dimension=28, opacity=48)
Click the icon to see the answer.
Answer 3 is the best choice here. Although it is tempting to keep sample code as short as possible, omitting parameter names makes it
harder for novices to learn.
Commented
Consider the following recommendations about comments in sample code:
Keep comments short, but always prefer clarity over brevity.
Avoid writing comments about obvious code, but remember that what is obvious to you (the expert) might not be obvious to
newcomers.
Focus your commenting energy on anything non-intuitive in the code.
When your readers are very experienced with a technology, don't explain what the code is doing, explain why the code is doing it.
Should you place descriptions of code inside code comments or in text (paragraphs or lists) outside of the sample code? Note that
readers who copy-and-paste a snippet gather not only the code but also any embedded comments. So, put any descriptions that belong in
the pasted code into the code comments. By contrast, when you must explain a lengthy or tricky concept, you should typically place the
text before the sample program.
Note: If you must sacri ce production readiness in order to make the code shorter and easier to understand, explain your decisions in the comments.
Exercise
What problems do you see in the comments within the following snippet? Assume that the code is aimed at programmers who are new to
the br API but who have some experience with the concept of streams:
/* Create a stream from the text file at pathname /tmp/myfile. */
mystream = br.openstream(pathname="/tmp/myfile", mode="z")
Click the icon to see the answer.
The comments contain the following aws:
add_circle
The comment elaborates on a fairly obvious part of the code.
add_circle The snippet doesn't explain the non-obvious portion of the code. Namely, what is the mode parameter and what does a value of z mean?
Reusable
For your reader to easily reuse your sample code, provide the following:
All information necessary to run the sample code, including any dependencies and setup.
Code that can be extended or customized in useful ways.
Having easy-to-understand sample code that's concise and compiles is a great start. If it blows up your reader's app, though, they won't be
happy. Therefore, when writing sample code, consider any potential side effects caused by your code being integrated into another
program. Nobody wants insecure or grossly ine cient code.
The example and the anti-example
In addition to showing readers what to do, it is sometimes wise to show readers what not to do. For example, many programming
languages permit programmers to place white space on either side of the equals sign. Now suppose that you were writing a tutorial on a
language (such as bash) that does not permit white space on either side of the equals sign. In this case, showing both a good example
and an anti-example will bene t the reader. For example:
# A valid string assignment.
s="The rain in Maine."
# An invalid string assignment because of the white space on either side of the
# equals sign.
s = "The rain in Maine."
Sequenced
A good sample code set demonstrates a range of complexity.
Readers completely unfamiliar with a certain technology typically crave simple examples to get started. The rst and most basic example
in a sample code set is usually termed a Hello World program (https://wikipedia.org/wiki/%22Hello,_World!%22_program). After mastering the
basics, engineers want more complex programs. A good set of sample code provides a healthy range of simple, moderate, and complex
sample programs.
Exercise
Which of the following would be a good set of sample functions to support a tutorial introducing newcomers to the concept of functions?
1. The following set of functions:
a. A function that takes no parameters and doesn't return anything.
b. A function that takes one parameter but doesn't return anything.
c. A function that takes one parameter and returns one value.
d. A function that takes three parameters and returns one value.
thumb_up
2. The following set of functions:
thumb_down a. A function that takes three parameters and returns one value.
3. The following set of functions:
a. A function that takes one parameter and returns one value.
b. A function that takes three parameters and returns one value.
Click the icon to see the answer.
The best answer is 1. Providing samples that cover a range of complexity is usually the wisest choice—particularly for newcomers. Resist
the temptation to rush towards very complex sample programs, bypassing the beginner and intermediate sample programs that
newcomers crave.
What's next?
Congratulations: you've completed the pre-class work for Technical Writing Two.
If the in-class portion of Technical Writing Two is available in your organization, please take it. If you'd like to facilitate the in-class portion
of Technical Writing Two, see the facilitator's guide (/tech-writing/for-instructors/two/instructors-guide).
A quick compilation of the topics covered in Technical Writing Two is available on the Summary (/tech-writing/two/summary) page.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC.
add_circle Documents Estimated Time: 10 minutes
You can write sentences. You can write paragraphs. Can you organize all those paragraphs into a coherent document?
State your document's scope
A good document begins by de ning its scope. For example:
This document describes the design of Project Frambus.
A better document additionally de nes its non-scope—the topics not covered that the target audience might reasonably expect your
document to cover. For example:
This document does not describe the design for the related technology, Project Froobus.
Scope and non-scope statements bene t not only the reader but also the writer (you). 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 rst draft, delete any sections that don't help satisfy the scope statement.
Exercise
What problem do you see in the following paragraph?
This document explains how to use the Frambus API to create, update, and publish Fwidgets. This document does not explain how to
use the Frambus API to delete Fwidgets or cover the history of the Linux operating system.
Click the icon to see the answer.
The non-scope should only include information that users would reasonably expect the document to cover. No reasonable user would
expect the document to cover the history of the Linux operating system.
State your audience
A good document explicitly speci es its audience. For example:
This document is aimed at the following audiences:
software engineers
program managers
Beyond the audience's role, a good audience declaration might also specify any prerequisite knowledge or experience. For example:
This document assumes that you understand matrix multiplication and the fundamentals of backpropagation.
In some cases, the audience declaration should also specify prerequisite reading or coursework. For example:
You must read "Project Froobus: A New Hope" prior to reading this document.
Summarize key points at the start
add_circle 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 rst paragraph of your document. Therefore, ensure that the start of your document answers your readers' essential
questions.
Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, the start of
any long document is the hardest page to write. Be prepared to revise page one many times.
Compare and contrast
In your career, no matter how creative you are, you will author precious few documents containing truly revolutionary ideas. Most of your
work will be evolutionary, building on existing technologies and concepts. Therefore, compare and contrast your ideas with concepts that
your audience already understands. For example:
This new app is similar to the Frambus app, except with much better graphics.
Or:
The Froobus API handles the same use cases as the Frambus API, except that the Froobus API is much easier to use.
Exercise
What problem do you see in the following introduction?
Frambus Weather app v2 introduces ten features not available in Frambus Weather app v1. Most importantly, v2 offers two-week
forecasts, v1 offered only one-week forecasts. Tidal information won't change.
Click the icon to see the answer.
The nal sentence (about tides) isn't important enough to appear in the opening paragraph. The rst sentence mentioned ten new
features, so readers would likely expect to hear more about those new features. Instead, the nal sentence refers to something other than
a new feature.
Write for your audience
This course repeatedly emphasizes the importance of de ning your audience. In this section, we focus on audience de nition as a means
of organizing your document.
De ne your audience's needs
Answering the following questions helps you determine what your document should contain:
Who is your target audience?
What is your target audience's goal? Why are they reading this document?
What do your readers already know before they read your document?
What should your readers know or be able to do after they read your document?
For example, suppose you have invented a new sorting algorithm, which is similar to quicksort. The following list contains some potential
answers to the preceding questions:
Who is your target audience? The target audience consists of all the software engineers in my organization.
What is your target audience's goal? My target audience wants to nd more e cient ways to sort data. They are reading this
document to determine whether this new algorithm is worth implementing.
What do your readers already know before they read your document? My target audience knows how to write code and has
previously studied sorting algorithms, including quicksort. However, most people in my target audience haven't implemented or
evaluated a sorting algorithm in several years.
add_circle What should your readers know or be able to do after they read your document? My target audience will be able to do all of the following:
Understand how the algorithm compares and contrasts with quicksort.
Identify the two kinds of datasets for which the algorithm outperforms the quicksort algorithm.
Implement the algorithm in their choice of programming language.
Identify the two edge cases in which the algorithm performs poorly.
Organize the document to meet your audience's needs After de ning the audience's needs, organize the document to help readers get the information they need. For example, based on the
answers in the previous section, the outline for the document could look as follows:
-
Overview of the algorithm
Compare and contrast with quicksort, including Big O comparisons Link to Wikipedia article on quicksort Optimal datasets for the algorithm -
Implementing the algorithm
Implementation in pseudocode Implementation tips, including common mistakes -
Deeper analysis of algorithm
Edge cases Known unknowns
Next unit: Punctuation (/tech-writing/one/punctuation), an optional unit
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Illustrating
Estimated Time: 10 minutes
Remember when your teacher assigned you a hefty chapter to read? You ipped through the assigned section of the textbook, desperately
hoping for...yes, pictures! Viewing illustrations was so much more fun than reading text. In fact, when it comes to reading technical
material, the vast majority of adults are still little kids—still yearning for pictures rather than text.
Figure 1. Good graphics engage readers in ways that text cannot.
Nirmal Dulal [CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0)] (https://commons.wikimedia.org/wiki/File:Nepalese_Children.JPG)
According to research by Sung and Mayer (2012) (https://www.sciencedirect.com/science/article/pii/S0747563212000921), providing any graphics—good or bad—makes readers like the document more; however, only instructive graphics help readers learn. This unit suggests a
few ways to help you create gures truly worth a thousand words.
Write the caption rst It is often helpful to write the caption before creating the illustration. Then, create the illustration that best represents the caption. This
process helps you to check that the illustration matches the goal.
Good captions have the following characteristics:
They are brief. Typically, a caption is just a few words.
They explain the takeaway. After viewing this graphic, what should the reader remember?
They focus the reader's attention. Focus is particularly important when a photograph or diagram contains a lot of detail.
Note: By convention, the caption always follows the diagram.
Exercise Target Audience: CS undergraduate students taking an "Introduction to Data Structures" class.
Consider the following three gures, each of which uses the same caption.
Caption A. A singly linked list node stores content and a reference to the next node.
Caption B. A singly linked list node stores content and a reference to the next node.
Caption C. A singly linked list node stores content and a reference to the next node.
Which of the three preceding gures best illustrates its caption?
Click the icon to see the answer.
Figure A is bad. The chain is pretty, but information-free. The chain also erroneously implies that a single-linked list points both
backwards and forwards.
Figure B is okay. The illustration helps students realize that the rst item points to the second item, the second points to the third,
and so on. However, although the caption refers to both content and a pointer, the illustration shows pointers but does not show
content.
Figure C is the best and most instructive choice. The illustration clearly delineates the content part of each node from the pointer
part.
Constrain the amount of information in a single drawing
Few intellectual tasks can be quite as rewarding as studying a ne painting, gradually uncovering layers of insight and meaning. People
pay good money to do exactly that in the world's art museums.
add_circle Figure 2. You'd happily study this Van Gogh painting.
Portrait of Pere Tanguy By Vincent van Gogh - Musée Rodin [Public domain]
(https://commons.wikimedia.org/wiki/File:Van_Gogh_-_Portrait_of_Pere_Tanguy_1887-8.JPG)
By contrast, highly complex technical illustrations like the following tend to discourage most readers: Figure 3. Complex block diagrams overwhelm readers.
Just as you avoid overly-long sentences, strive to avoid visual run-ons. As a rule of thumb, don't put more than one paragraph's worth of
information in a single diagram. (An alternative rule of thumb is to avoid illustrations that require more than ve bulleted items to explain.)
I can hear you saying, "But real-life technical systems can be vastly more complex than the one shown in Figure 3." You are correct, but you
probably don't feel compelled to explain real-life complex systems in a single paragraph.
The trick to reducing visual clutter into something coherent and helpful is to organize complex systems into subsystems, like those shown
in the following gure: Figure 4. A complex system organized into three subsystems.
After showing the "big picture," provide separate illustrations of each subsystem.
Figure 5. Expanded detail for one subsystem of a complex system.
Alternatively, start with a simple "big picture" and then gradually expand detail in each subsequent illustration.
Focus the reader's a ention When confronted with a complex screenshot like the following, readers struggle to determine what's relevant: Figure 6. Readers don't know what to focus on.
Adding a visual cue, for example, the red oval in the following gure, helps readers focus on the relevant section of the screenshot:
Figure 7. Readers focus on a shape that breaks the pattern.
Callouts provide another way to focus the reader's attention. For pictures and line art, a callout helps our eyes nd just the right spot to
land on. Callouts in pictures are often better than paragraph long explanations of the pictures because callouts focus the reader's
attention on the most important aspects of the picture. Then, in your explanation, you can focus directly on the relevant part of the
diagram, rather than spending time describing what part of the image you are talking about.
In the example image, the callout and arrow quickly direct the reader to the purpose. Figure 8. A callout directs readers' eyes.
NASA / JPL-Caltech / University of Arizona [Public domain] (https://commons.wikimedia.org/wiki/File:Phobos_colour_2008.jpg)
Illustrating is re-illustrating As with writing, the rst draft of an illustration is seldom good enough. Revise your illustrations to clarify the content. As you revise, ask
yourself the following questions:
How can I simplify the illustration?
Should I split this illustration into two or more simpler illustrations?
Is the text in the illustration easy to read? Does the text contrast su ciently with its background?
What's the takeaway?
For instance, consider the evolution of the London Tube map (https://wikipedia.org/wiki/Tube_map#History). Prior to 1931, the Tube map was drawn to scale, complete with above ground roads and tube lines that curved as the tracks did. Figure 9. 1908 to scale map of the London Tube with above ground roads.
[Public domain] (https://commons.wikimedia.org/wiki/File:Tube_map_1908.jpg)
In 1931, Harry Beck pioneered a new type of public transit map that simpli ed the older map by removing above ground markers and
removing scale. His design instead focused on what people using the maps really cared about: getting from station A to station B. Even
with the success of his 1931 map, Beck still iterated on the diagram for many years to simplify and clarify the map. Consider now the
modern tube map (https://www.google.com/search?tbm=isch&q=london+tube+map), although new lines and stations have appeared, they still remain close to Beck's design.
Exercise Consider the following original illustration: Figure 10. A complex diagram.
The takeaway of the preceding diagram is supposed to be:
For a recursive solution, call the function itself in the return statement until you reach a base case solution.
In what ways does the complexity of the diagram hide the takeaway? How might you address these problems?
Click the icon to see the answer.
Some possible issues with the diagram include:
Issue: The bright colors pull the reader's attention away from other aspects of the diagram.
Solution: Choose colors carefully so that they do not overpower the diagram.
Issue: The diagram does not have su cient color contrast. This makes the diagram inaccessible for some people with low vision or
certain types of color blindness.
Solution: Remove unnecessary use of color and ensure that colors pass standard color contrast recommendations
(https://material.io/design/color/text-legibility.html#legibility-standards).
Issue: The arrows point in both directions which makes it unclear which way the diagram ows.
Solution: Separate the arrows into two parts with one set illustrating invoking a function and the other set illustrating returning from
the function.
There are additional issues in the diagram that are not identi ed here.
Here is an improved illustration:
add_circle Figure 11. A simpli ed version of the preceding diagram.
What aws do you see in the improved illustration?
Click the icon to see the answer.
Here are two of the aws that still exist:
This diagram is still too complex. It would take far more than a paragraph to explain this illustration. Consider how removing extra
information or adding clarifying labels might simplify the interpretation.
While separating the arrows helped display when the functions invoke or return data to each other, the return arrows might bene t
from labels that tell the reader what the return values are.
Illustration tools
There are many options available for creating diagrams. Three options that are free or have free options include:
Google Drawings (https://drawings.google.com)
diagrams.net (https://diagrams.net)
LucidChart (https://www.lucidchart.com/pages/)
When exporting diagrams from these tools to use in documentation, it is usually best to export the les as Scalable Vector Graphics
(https://wikipedia.org/wiki/Scalable_Vector_Graphics) (SVG). The SVG format easily scales diagrams based on space constraints so that no
matter the size, you end up with a high quality image.
Next unit: Creating sample code (/tech-writing/two/sample-code)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC.
add_circle Just enough grammar (optional)
Estimated Time: 10 minutes
This unit provides just enough grammar to understand the remainder of the course. If you already know some grammar, move on to Words
(/tech-writing/one/words). Otherwise, read on.
For simplicity's sake, this unit takes a few shortcuts; grammatical topics are actually wildly more complicated than this unit suggests.
Grammarians don't all agree on the number or types of parts of speech. The following table focuses on the parts of speech relevant to this
course:
Part of Speech De nition Example
Noun A person, place, concept, or thing Sam runs races.
Pronoun A noun that replaces another noun (or larger structure) Sam runs races. He likes to compete.
Adjective A word or phrase that modi es a noun Sam wears blue shoes.
Verb An action word or phrase Sam runs races.
Adverb A word or phrase that modi es a verb, an adjective, or another adverb Sam runs slowly.
Preposition A word or phrase specifying the positional relationship of two nouns Sam's sneakers are seldom on his shelf.
Conjunction A word that connects two nouns or phrases Sam's trophies and ribbons live only in his imagination.
Transition A word or phrase that connects two sentences Sam runs races weekly. However, he nishes races weakly.
Nouns
Nouns represent people, places, or things. Judy, Antarctica, and hammers are all nouns, but so are intangible concepts like robustness
and perfection. In the following example passage, we've formatted the nouns in bold:
In the framework, an object must copy any underlying values that the object wants to change. The protocol buffers in the codebase are
huge, so copying the protocol buffers is unacceptably expensive.
In programming, you might think of classes and variables as your program's nouns.
Exercise
Identify the six nouns in the following passage:
C enables programmers to control pointers and memory. Great power brings great responsibility.
Click the icon to see the answer.
You can nd the nouns in boldface:
C enables programmers to control pointers and memory. Great power brings great responsibility.
Now suppose the second sentence was the following:
Great control brings great responsibility.
Is "control" a verb or is it a noun?
In this context, "control" is a noun, even though "to control" in the rst sentence is a verb. Many words in English serve as a noun in some
contexts and a verb in others.
add_circle Pronouns Pronouns are an indirection layer—pointers to or substitutions for other nouns or sentences. For example, consider the following two
sentences:
Janet writes great code. She is a senior staff engineer.
In the preceding example, the rst sentence establishes Janet as a noun. The second sentence replaces the noun Janet with the pronoun
She.
In the following example, the pronoun This replaces an entire sentence:
Most applications aren't su ciently tested. This is poor engineering.
Exercise
Identify the three pronouns in the following passage:
The cafeteria featured peanut butter and plum jam on rye toast. Employees found it awesome and wished they could eat this every day.
Click the icon to see the answer.
The cafeteria featured peanut butter and plum jam on rye toast. Employees found it awesome and wished they could eat this every day.
Verbs
A verb is an action word or phrase. When you want to represent the relationship between two nouns (an actor and a target), the verb does
the work. A verb identi es what the actor does to the target.
Each sentence must contain at least one verb. For example, each of the following sentences contain a single verb:
Sakai prefers pasta.
Rick likes the ocean.
Smurfs are blue.
Jess suffers from allergies.
Some sentences, such as the following, contain multiple verbs:
Nala suffers from allergies and sneezes constantly.
The program runs slowly but fails quickly.
Depending on the tense and the conjugation, a verb could consist of one word or multiple words. For example:
Tina was eating breakfast a few hours ago.
Tina is eating lunch right now.
Tina will eat dinner tonight at 7:00.
Exercise
Identify the verbs in the following passage:
Samantha is coding Operation Bullwinkle in C++. This project currently consumes over 80,000 lines of code. She previously used Python,
but recently gravitated to C++. Samantha leads a team of four software engineers, which will grow to six software engineers next
quarter.
add_circle Click the icon to see the answer.
Samantha is coding Operation Bullwinkle in C++. This project currently consumes over 80,000 lines of code. She previously used
Python, but recently gravitated to C++. Samantha leads a team of four software engineers, which will grow to six software engineers
next quarter.
Adjectives and adverbs
Adjectives modify nouns. For example, in the following passage, notice how the adjectives modify the subsequent noun:
Tom likes red balloons. He prepares delicious food. He xed eight bugs at work.
Most adverbs modify verbs. For example, notice how the adverb (e ciently) in the following sentence modi es the verb ( xes):
Jane e ciently xes bugs.
Adverbs are not necessarily right next to their verb. For example, in the following sentence, the adverb (e ciently) is two words away from
the verb ( xes):
Jane xes bugs e ciently.
Adverbs can also modify adjectives or other adverbs.
Exercise
Identify the four adjectives in the following passage:
Engineering is a great career for a brilliant mind. I know a clever engineer who could excel at any intellectual task.
Click the icon to see the answer.
Engineering is a great career for a brilliant mind. I know a clever engineer who could excel at any intellectual task.
Prepositions
Prepositions specify the relationship between two things. Some prepositions answer the question, "Where is this thing relative to that
other thing?" For example:
The submenu lies under the menu.
The de nition appears next to the term.
The print function falls within the main routine.
Other prepositions answer the question, "When is this event relative to that other event?" For example:
The program evaluates the addition operation before evaluating the subtraction operation.
The cron daemon executes the script every Tuesday at noon.
A few prepositions (for example, by and of) answer other kinds of questions about relationships. For example, the following sentence
uses by to relate a book to its authors:
The C Programming Language by Kernighan and Richie remains popular.
Note: Some English words fall into multiple grammatical categories. For example, although under is usually a preposition, under can also serve as an adverb
or adjective depending on context.
add_circle
Exercise
add_circle Identify the two prepositions in the following passage:
Parameters may optionally appear within a URL, after the path.
Click the icon to see the answer.
Parameters may optionally appear within a URL, after the path.
Conjunctions and transitions
Conjunctions connect phrases or nouns within a sentence; transitions connect sentences themselves.
The most important conjunctions are as follows:
And
But
Or
For example, in the following sentence, and connects "code" with "documentation," while but connects the rst half of the sentence with
the second.
Olivia writes great internal code and documentation but seldom works on open-source projects.
The most important transitions in technical writing are as follows:
However
Therefore
For example
For example, in the following passage, notice how the transitions connect and contextualize the sentences:
Juan is a wonderful coder. However, he rarely writes su cient tests. For example, Juan coded a 5,000 line FFT package that contained
only a single 10-line unit test.
Exercise
Fill in the most appropriate transition:
Barbara typically studies problems for a long time before writing the rst line of code. _____________, she spontaneously coded a method
the other day when she was suddenly inspired.
Click the icon to see the answer.
The best transition for this situation is as follows:
However
Next unit: Words (/tech-writing/one/words)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
add_circle
Last updated 2024-09-09 UTC.
add_circle Lists and tables
Estimated Time: 15 minutes
Good lists can transform technical chaos into something orderly. Technical readers generally love lists. Therefore, when writing, seek
opportunities to convert prose into lists.
Choose the correct type of list 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.
For example, we've made the following a bulleted list because rearranging its items does not change the list's meaning:
Bash provides the following string manipulation mechanisms:
Deleting a substring from the start of a string
Reading an entire le into one string variable
The following list, by contrast, must be a numbered list because rearranging its items would change the list's meaning:
Take the following steps to recon gure the server:
1. Stop the server.
2. Edit the con guration le.
3. Restart the server.
An embedded list (sometimes called a run-in list) contains items stuffed within a sentence. For example, the following sentence contains
an embedded list with four items.
The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicunas, and track dromedaries.
Generally speaking, embedded lists are a poor way to present technical information. Try to transform embedded lists into either bulleted
lists or numbered lists. For example, you should convert the sentence containing the embedded list into the following passage:
The llamacatcher API enables callers to do the following:
Create and query llamas.
Analyze alpacas.
Delete vicunas.
Track dromedaries.
Exercise Convert the following paragraph into one or more lists:
Today at work, I have to code three unit tests, write a design document, and review Janet's latest document. After work, I have to wash
my car without using any water and then dry it without using any towels.
Don't forget to introduce your list(s).
Click the icon to see the answer.
Here's one possible answer:
I must do the following at work today:
Code three unit tests.
Write a design document.
Review Janet's latest document.
After work, I must do the following:
1. Wash my car without using any water.
2. Dry my car without using any towels.
The following is an alternative answer:
I must do the following tasks today:
At work:
Code three unit tests.
Write a design document.
Review Janet's latest document.
After work:
1. Wash my car without using any water.
2. Dry my car without using any towels.
Keep list items parallel
What separates effective lists from defective 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.
For example, the following list is parallel because all the items are plural nouns (grammar), edible (logical category), in title case
(capitalization), and without periods or commas (punctuation).
Carrots
add_circle
Potatoes
Cabbages
By contrast, the following list is painfully nonparallel along all parameters:
Carrots
Potatoes
The summer light obscures all memories of winter.
The following list is parallel because all the items are complete sentences with complete sentence capitalization and punctuation:
Carrots contain lots of Vitamin A.
Potatoes taste delicious.
Cabbages provide oodles of Vitamin K.
The rst item in a list establishes a pattern that readers expect to see repeated in subsequent items.
Exercise
Is the following list parallel or nonparallel?
Broccoli inspires feelings of love or hate.
Potatoes taste delicious.
Cabbages.
Click the icon to see the answer.
The list is nonparallel. The rst two items are complete sentences, but the third item is not a sentence. (Don't be fooled by the
capitalization and punctuation of the third item.)
Exercise
Is the following list parallel or nonparallel?
The red dots represent sick trees.
Immature trees are represented by the blue dots.
The green dots represent healthy trees.
Click the icon to see the answer.
This is a nonparallel list. The rst and third items are in active voice, but the second item is in passive voice.
Start numbered list items with imperative verbs
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:
1. Download the Frambus app from Google Play or iTunes.
2. Con gure the Frambus app's settings.
3. Start the Frambus app.
The following numbered list is nonparallel because two of the sentences start with an imperative verb, but the third item does not:
1. Instantiate the Froobus class.
2. Invoke the Froobus.Salmonella() method.
3. The process stalls.
add_circle add_circle Exercise Make the following list parallel. Ensure that each element in the result list begins with an imperative verb:
1. Stop Frambus
2. The key con guration le is /etc/frambus. Open this le with an ASCII text editor.
3. In this le, you will see a parameter named Carambola, which is currently set to the default value (32). Change this value to 64.
4. When you are nished setting this parameter, save and close the con guration le
5. now, start Frambus again.
Click the icon to see the answer.
The following is one possible answer:
1. Stop Frambus.
2. Open the key con guration le, /etc/frambus, with an ASCII text editor.
3. Change the Carambola parameter from its default value (32) to 64.
4. Save and close the con guration le.
5. Restart Frambus.
Punctuate items appropriately
Though different style guides offer con icting advice about punctuating list items, the Google developer documentation style guide
(https://developers.google.com/style/lists#capitalization-and-end-punctuation) recommends (with some exceptions) starting each list item with a
capital letter. For example:
Loops
Conditionals
Variable declarations
If a list item is a sentence, use appropriate sentence-ending punctuation. For example:
1. Open the program.
2. Click the settings icon.
Create useful tables
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.
Note: Some tables don't render well across all form factors. For example, a table that looks great on your laptop may look awful on your phone.
add_circle Introduce each list and table 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. For example, consider the following
introductory sentences:
The following list identi es key performance parameters:
Take the following steps to install the Frambus package:
The following table summarizes our product's features against our key competitors' features:
Exercise
Write an introductory sentence for the following table:
Language Inventor Year Introduced Key Feature
Lisp John McCarthy 1958 recursion
C++ Bjarne Stroustrup 1979 OOP
Python Guido van Rossum 1994 simplicity
Click the icon to see the answer.
Here are a couple of possible introductory sentences for the table:
The following table contains a few key facts about some popular programming languages:
The following table identi es the inventor, year of invention, and key feature of three popular programming languages:
Next unit: Paragraphs (/tech-writing/one/paragraphs)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-09-25 UTC.
add_circle Markdown (optional) Estimated Time: 10 minutes
Markdown is a lightweight markup language that many technical professionals use to create and edit technical documents. With
Markdown, you write text in a plain text editor (such as vi or Emacs), inserting special characters to create headers, boldface, bullets, and
so on. For example, the following example shows a simple technical document formatted with Markdown:
bash closely resembles an older shell named ksh. The key practical difference between the two shells is as follows:
- More people know bash than ksh, so it is easier to get help for bash problems than ksh problems.
The rendered version of the preceding technical document looks as follows:
bash and ksh bash closely resembles an older shell named ksh . The key practical difference between the two shells is as follows:
More people know bash than ksh, so it is easier to get help for bash problems than ksh problems.
A Markdown parser converts Markdown les into HTML. Browsers can then display the resulting HTML to readers.
We recommend becoming comfortable with Markdown by taking one of the following tutorials:
www.markdowntutorial.com (https://www.markdowntutorial.com/)
Mastering Markdown (https://guides.github.com/features/mastering-markdown/)
What's next? Congratulations: you've completed the pre-class work for Technical Writing One.
If the in-class portion of Technical Writing One is available in your organization, please take it. If you'd like to facilitate the in-class portion
of Technical Writing One, see the facilitator's guide (/tech-writing/for-instructors/one/instructors-guide).
A quick compilation of the topics covered in Technical Writing One is available on the Summary (/tech-writing/one/summary) page.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Organizing large documents Estimated Time: 20 minutes
How do you organize a large collection of information into a cohesive document or website? Alternatively, how do you reorganize an
existing messy document or website into something approachable and useful? The following tactics can help:
Choosing to write a single, large document or a set of documents
Organizing a document
Adding navigation
Disclosing information progressively
When to write large documents You can organize a collection of information into longer standalone documents or a set of shorter interconnected documents. A set of
shorter interconnected documents is often published as a website, wiki, or similar structured format.
Some readers respond more positively than others to longer documents. Consider the following perspectives from two hypothetical
readers you're writing documentation for:
Hong nds reading long documents di cult and disorientating. He prefers to use site search to nd answers to his questions.
Rose is comfortable navigating large documents. She often uses the built-in page search feature in her web browser to nd useful
information on the current page.
So, should you organize your material into a single document or into a set of documents in a website? Consider the following guidelines:
How-to guides, introductory overviews, and conceptual guides often work better as shorter documents when aimed at readers who
are new to the subject matter. For example, a reader who is completely new to your subject matter might struggle to remember lots
of new terms, concepts, and facts. Remember that your audience might be reading your documentation to gain a quick and general
overview of the topic.
In-depth tutorials, best practice guides, and command-line reference pages can work well as lengthier documents, especially when
aimed at readers who already have some experience with the tools and subject matter.
A great tutorial can rely on a narrative to lead the reader through a series of related tasks in a longer document. However, even large
tutorials can sometimes bene t from being broken up into smaller parts.
Many longer documents aren't designed to be read in one sitting. For example, users typically scan through a reference page to
search for an explanation of a command or ag.
The remainder of this unit covers techniques that can be useful for writing longer documents, such as tutorials and some conceptual
guides.
Organize a document This section suggests some techniques for planning a longer document, including creating an outline and drafting an introduction. After
you've completed the rst draft of a document, you can review it against your outline and introduction to make sure you haven't missed
anything you originally intended to cover.
Outline a document Starting with a structured, high-level outline can help you group topics and determine where more detail is needed. The outline helps you
move topics around before you get down to writing.
You might nd it useful to think of an outline as the narrative for your document. There is no standard approach to writing an outline, but
the following guidelines provide practical tips you might nd useful: Before you ask your reader to perform a task, explain to them why they are doing it. For example, the following bullet points illustrate
a section of an outline from a tutorial about auditing and improving the accessibility of web pages:
Introduce a browser plugin that audits the accessibility of web pages; explain that the reader will use the results of the audit
report to x several bugs.
List the steps to run the plugin and audit the accessibility of a web page.
Limit each step of your outline to describing a concept or completing a speci c task.
Structure your outline so that your document introduces information when it's most relevant to your reader. For example, your reader
probably doesn't need to know (or want to know) about the history of the project in the introductory sections of your document when
they're just getting started with the basics. If you feel the history of the project is useful, then include a link to this type of information
at the end of your document.
Consider explaining a concept and then demonstrating how the reader can apply it either in a sample project or in their own work.
Documents that alternate between conceptual information and practical steps can be a particularly engaging way to learn.
Before you start drafting, share the outline with your contributors. Outlines are especially useful if you're working with a team of
contributors who are going to review and test your document.
Outline exercise
Review and update the following high-level outline of an introduction to a long tutorial. To solve this exercise, you can do any of the
following:
Rearrange the existing topics.
Add any missing topics you feel should be in an introduction.
Remove any topics you feel are irrelevant for an introduction.
## The history of the project
Describes the history of the development of the project.
## Prerequisites
Lists concepts the reader should be familiar with prior to starting, as well as
any software or hardware requirements.
## The design of the system
Describes how the system works.
## Audience
Describes who the tutorial is aimed at.
## Setting up the tutorial
Explains how to configure your environment to follow the tutorial.
## Troubleshooting
Explains how to diagnose and solve potential problems that might occur when
working through the tutorial.
## Useful terminology
Lists definitions of terms that the reader needs to know to follow the
tutorial.
Click the icon to see a possible answer.
The following is one possible solution:
add_circle ## Audience
Describes who the tutorial is aimed at.
Lists concepts the reader should be familiar with prior to starting, as well as any software or hardware requirements.
Explains how to configure your environment to follow the tutorial.
Lists definitions of terms that the reader needs to know to follow the tutorial.
Introduce a document If readers of your documentation can't nd relevance in the subject, they are likely to ignore it. To set the ground rules for your users, we
recommend providing an introduction that includes the following information:
What the document covers.
What prior knowledge you expect readers to have.
What the document doesn't cover.
Remember that you want to keep your documentation easy to maintain, so don't try to cover everything in the introduction.
The following paragraph demonstrates the ideas from the preceding list as an overview for a hypothetical document publishing platform
called Froobus:
This document explains how to publish Markdown files using the Froobus system. Froobus is a publishing system that runs on a Linux server and converts Markdown files into HTML pages. This document is intended for people who are familiar with Markdown syntax. To learn about the syntax, see the Markdown reference. You also need to be comfortable running simple commands in a Linux terminal. This document doesn't include information about installing or configuring a Froobus publishing system. For information on installing Froobus, see Getting started.
After you've completed the rst draft, check your entire document against the expectations you set in your overview. Does your
introduction provide an accurate overview of the topics you cover? You might nd it useful to think of this review as a form of
documentation quality assurance (QA).
Introduction exercise For this exercise, review and revise the following introduction for a best practices guide for a hypothetical programming language called
F@. Remove any information you feel is irrelevant in this context and add any information you feel is missing.
This guide lists best practices for working with the F@ programming language. F@ was developed in 2011 as an open source community project. This guide supplements the F@ style guide. In addition to the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. The programming language is widely adopted in the health industry. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository. Click the icon to see a possible answer.
The following is one possible solution:
This guide lists best practices for working with the F@ programming language.
Before you review this guide, complete the introductory tutorial for new F@
developers. This guide supplements the F@ style guide. In addition to the best
practices in this guide, make sure you also install the F@ command-line linter
and run it on your code. If you have suggestions for additions to the list of
best practices, file an issue in the F@ documentation repository.
Add navigation
Providing navigation and signposting for your readers ensures they can nd what they are looking for and the information they need to get
unstuck.
Clear navigation includes:
introduction and summary sections
a clear, logical development of the subject
headings and subheadings that help users understand the subject
a table of contents menu that shows users where they are in the document
links to related resources or more in-depth information
links to what to learn next
The tips in the following sections can help you plan the headings in your documentation.
Prefer task-based headings
Choose a heading that describes the task your reader is working on. Avoid headings that rely on unfamiliar terminology or tools. For
example, suppose you are documenting the process for creating a new website. To create the site, the reader must initialize the Froobus
framework. To initialize the Froobus framework, the reader must run the carambola command-line tool. At rst glance, it might seem
logical to add either of the following headings to the instructions:
Running the carambola command
Initializing the Froobus framework
Unless your readers are already very experienced with the terminology and concepts for this topic, a more familiar heading might be
preferable, such as Creating the site.
Provide text under each heading
Most readers appreciate at least a brief introduction under each heading to provide some context. Avoid placing a level three heading
immediately after a level two heading, as in the following example:
## Creating the site
### Running the carambola command
In this example, a brief introduction can help orient the reader:
## Creating the site
add_circle
To create the site, you run the `carambola` command-line tool. The command
displays a series of prompts to help you configure the site.
### Running the carambola command
Heading exercise
Helping readers navigate through your documentation helps them nd the information they need to successfully use your tool. Often, a
clear and well-organized table of contents or outline acts like a map that helps your users navigate the functionality of your tool.
For this exercise, improve the following outline. You can rearrange, add, and delete topics and create secondary entries too.
About this tutorial
Advanced topics
Build the asset navigation tree
Define resource paths
Defining and building projects
Launch the development environment
Defining and building resources
What's next
Define image resources
Audience
See also
Build an image resource
Define an image project
Build an image project
Setting up the tutorial
Select the tutorial asset root
About this guide
Click the icon to see a possible answer.
The following is one possible solution:
## About this tutorial
### Audience
### About this guide
### Advanced topics
## Setting up the tutorial
### Select the tutorial asset root
### Launch the development environment
### Build the asset navigation tree
### Define resource paths
## Defining and building resources
### Define image resources
### Build an image resource
## Defining and building projects
### Define an image project
### Build an image project
## Defining and building databases
add_circle ### Define a database
Disclose information progressively Learning new concepts, ideas, and techniques can be a rewarding experience for many readers who are comfortable reading through
documentation at their own pace. However, being confronted with too many new concepts and instructions too quickly can be
overwhelming. Readers are more likely to be receptive to longer documents that progressively disclose new information to them when
they need it. The following techniques can help you incorporate progressive disclosure in your documents:
Where possible, try introducing new terminology and concepts near the instructions that rely on them.
Break up large walls of text. To avoid multiple large paragraphs on a single page, aim to introduce tables, diagrams, lists, and
headings where appropriate.
Break up large series of steps. If you have a particularly long list of complicated steps, try to re-arrange them into shorter lists that
explain how to complete sub-tasks.
Start with simple examples and instructions, and add progressively more interesting and complicated techniques. For example, in a
tutorial for creating forms, start by explaining how to handle text responses, and then introduce other techniques to handle multiple
choice, images, and other response types.
Next unit: Illustrating (/tech-writing/two/illustrations)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Paragraphs
Estimated Time: 10 minutes
This unit provides some guidelines on building cohesive paragraphs. But rst, here is an inspirational message:
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.
Write a great opening sentence
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. For example, the following paragraph features an effective opening
sentence:
A loop runs the same block of code multiple times. For example, suppose you wrote a block of code that detected whether an input line
ended with a period. To evaluate a million input lines, create a loop that runs a million times.
The preceding opening sentence establishes the theme of the paragraph as an introduction to loops. By contrast, the following opening
sentence sends readers in the wrong direction:
A block of code is any set of contiguous code within the same function. For example, suppose you wrote a block of code that detected
whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.
Exercise
Is the opening sentence of the following paragraph effective or defective?
The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse.
The k-means clustering algorithm relies on the Pythagorean Theorem to measure distances. By contrast, the k-median clustering
algorithm relies on the Manhattan Distance.
Click the icon to see the answer.
This opening sentence is defective because it implies that the paragraph will focus on the Pythagorean Theorem. In fact, the paragraph's
focus is actually clustering algorithms. The following would be a more effective opening sentence:
Different clustering algorithms measure distances differently.
Note: Effective opening sentences can take many forms. That is, not all great paragraphs start with a sentence that states the theme. Starting a paragraph
with a rhetorical question, for example, can engage readers.
Focus each paragraph on a single topic
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.
add_circle For example, assume that the opening sentence of the following paragraph does focus on the correct topic. Can you spot the sentences
that should be removed from the following paragraph?
The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse.
The perimeter of a triangle is equal to the sum of the three sides. You can use the Pythagorean Theorem to measure diagonal
distances. For example, if you know the length and width of a ping-pong table, you can use the Pythagorean Theorem to determine the
diagonal distance. To calculate the perimeter of the ping-pong table, sum the length and the width, and then multiply that sum by 2.
We've crossed out the second and fth sentences to yield a paragraph focused exclusively on the Pythagorean Theorem:
The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse.
The perimeter of a triangle is equal to the sum of the three sides. You can use the Pythagorean Theorem to measure diagonal
distances. For example, if you know the length and width of a ping-pong table, you can use the Pythagorean Theorem to determine the
diagonal distance. To calculate the perimeter of the ping-pong table, sum the length and the width, and then multiply that sum by 2.
Exercise
Remove the extraneous sentence(s) from the following paragraph. Assume that the opening sentence does establish the desired theme
for the paragraph:
Spreadsheets provide a great way to organize data. Think of a spreadsheet as a table with rows and columns. Spreadsheets also
provide mathematical functions, such as means and standard deviations. Each row holds details about one entity. Each column holds
details about a particular parameter. For example, you can create a spreadsheet to organize data about different trees. Each row would
represent a different type of tree. Each column would represent a different characteristic, such as the tree's height or the tree's spread.
Click the icon to see the answer.
The paragraph focuses on spreadsheets as a way of organizing data. The third sentence distracts from that theme. Move the third
sentence to another paragraph about mathematical operations in spreadsheets.
Spreadsheets provide a great way to organize data. Think of a spreadsheet as a table with rows and columns. Spreadsheets also
provide mathematical functions, such as means and standard deviations. Each row holds details about one entity. Each column holds
details about a particular parameter. For example, you can create a spreadsheet to organize data about different trees. Each row would
represent a different type of tree. Each column would represent a different characteristic, such as the tree's height or the tree's spread.
Don't make paragraphs too long or too short
Long paragraphs are visually intimidating. Very long paragraphs form a dreaded "wall of text" that readers ignore. Readers generally
welcome paragraphs containing three to ve 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.
Answer what, why, and how
Good paragraphs answer the following three questions:
1. What are you trying to tell your reader?
2. Why is it important for the reader to know this?
3. How should the reader use this knowledge? Alternatively, how should the reader know your point to be true?
For example, the following paragraph answers what, why, and how:
add_circle The garp() function returns the delta between a dataset's mean and median. Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily in uenced by a few very large or very
small data points. garp() to help determine whether a few very large or very small data points are Call
in uencing the mean too much. A relatively small garp() value suggests that the mean is more meaningful than when the garp()
value is relatively high.
Next unit: Audience (/tech-writing/one/audience)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Punctuation (optional)
Estimated Time: 5 minutes
This optional unit provides a quick refresher on punctuation marks.
Commas
Programming languages enforce clear rules about punctuation. In English, by contrast, the rules regarding commas are somewhat hazier.
As a guideline, insert a comma wherever a reader would naturally pause somewhere within a sentence. For the musically inclined, if a
period is a whole note (semibreve) rest, then a comma is perhaps a half-note (minim) or quarter-note (crotchet) rest. In other words, the
pause for a comma is shorter than that for a period. For example, if you read the following sentence aloud, you probably rest brie y before
the word just:
C behaves as a mid-level language, just a couple of steps up in abstraction from assembly language.
Some situations require a comma. For example, use commas to separate items in an embedded list like the following:
Our company uses C++, Python, Java, and JavaScript.
You might be wondering about a list's nal comma, the one inserted between items N-1 and N. This comma—known as the serial comma
or Oxford comma—is controversial. We recommend supplying that nal comma simply because technical writing requires picking the
least ambiguous solution. That said, we actually prefer circumventing the controversy by converting embedded lists into bulleted lists.
In sentences that express a condition, place a comma between the condition and the consequence. For example, both of the following
sentences supply the comma in the correct place:
If the program runs slowly, try the --perf ag.
If the program runs slowly, then try the --perf ag.
You can also wedge a quick de nition or digression between a pair of commas as in the following example:
Python, an easy-to-use language, has gained signi cant momentum in recent years.
Finally, avoid using a comma to paste together two independent thoughts. For example, the comma in the following sentence is guilty of a
punctuation felony called a comma splice:
Not recommended
Samantha is a wonderful coder, she writes abundant tests.
Use a period rather than a comma to separate two independent thoughts. For example:
Recommended
Samantha is a wonderful coder. She writes abundant tests.
Exercise
Add commas where appropriate to the following passage:
Protocol Buffers sometimes known as protobufs are our team's main structured data format. Use Protocol Buffers to represent store
and transfer structured data. Unlike XML Protocol Buffers are compiled. Consequently clients transmit Protocol Buffers e ciently which
has led to rapid adoption.
Hint: Read the passage aloud and put a comma everywhere you hear a short pause.
thumb_down thumb_up Click the icon to see the answer.
Here is one possible solution:
Protocol Buffers, sometimes known as protobufs, are our team's main structured data format. Use Protocol Buffers to represent, store,
and transfer structured data. Unlike XML, Protocol Buffers are compiled. Consequently, clients transmit Protocol Buffers e ciently,
which has led to rapid adoption.
Semicolons
A period separates distinct thoughts; a semicolon unites highly related thoughts. For example, notice how the semicolon in the following
sentence unites the rst and second thoughts:
Recommended
Rerun Frambus after updating your con guration le; don't rerun Frambus after updating existing source code.
Before using a semicolon, ask yourself whether the sentence would still make sense if you ipped the thoughts to opposite sides of the
semicolon. For example, reversing the earlier example still yields a valid sentence:
Don't rerun Frambus after updating existing source code; rerun Frambus after updating your con guration le.
The thoughts preceding and following the semicolon must each be grammatically complete sentences. For example, the following
semicolon is incorrect because the passage following the semicolon is a clause
(/tech-writing/one/short-sentences#reduce_subordinate_clauses_optional), not a complete sentence:
Not recommended
Rerun Frambus after updating your con guration le; not after updating existing source code.
Recommended
Rerun Frambus after updating your con guration le, not after updating existing source code.
You should almost always use commas, not semicolons, to separate items in an embedded list. For example, the following use of
semicolons is incorrect:
Not recommended
Style guides are bigger than the moon; more essential than oxygen; and completely inscrutable.
As mentioned earlier in this lesson, technical writing usually prefers bulleted lists to embedded lists. However, if you truly prefer an
embedded list, use commas rather than semicolons to separate the items, as in the following example:
Recommended
Style guides are bigger than the moon, more essential than oxygen, and completely inscrutable.
Many sentences place a transition word or phrase immediately after the semicolon. In this situation, place a comma after the transition.
Note the comma after the transition in the following two examples:
Frambus provides no o cial open source package for string manipulation; however, subsets of string manipulation packages are
available from other open source projects.
Even seemingly trivial code changes can cause bugs; therefore, write abundant unit tests.
add_circle
Exercise
thumb_up thumb_down thumb_up thumb_down thumb_up Which of the following periods or commas could you replace with a semicolon?
1. Python is a popular programming language. The C language was developed long before Python.
2. Model learning for a low value of X appears in the top illustration. Model learning for a high value of X appears in the bottom
illustration.
3. I'm thankful for my large monitor, powerful CPU, and blazing bandwidth.
Click the icon to see the answer.
1. You may not convert the period in #1 to a semicolon because the two sentences are only vaguely related.
2. You may replace the period in #2 with a semicolon because the two sentences are so highly related.
3. You may not convert the commas in #3 to semicolons. Use commas to separate items in an embedded list.
Em dashes
Em dashes are compelling punctuation marks, rich with punctuation possibilities. An em dash represents a longer pause—a bigger break—
than a comma. For the musically uent, think of a comma as a quarter note (crotchet) rest and an em dash as a half-note (minim) rest. For
example:
C++ is a rich language—one requiring extensive experience to fully understand.
Writers sometimes use a pair of em dashes to block off a digression, as in the following example:
Protocol Buffers—often nicknamed protobufs—encode structured data in an e cient yet extensible format.
Could we have used commas instead of em dashes in the preceding examples? Sure. Why did we choose an em dash instead of a
comma? Feel. Art. Experience.
En dashes and hyphens
Consider the horizontal punctuation marks shown in the following table:
Name Mark Relative width
em dash — widest (usually, the length of the letter m)
en dash – medium (usually, the length of the letter n)
hyphen - narrowest
Some style guides recommend the en dash for certain uses. The Google Style Guide (https://developers.google.com/style/dashes#en-dashes),
however, offers the following blunt advice about en dashes:
Don't use.
Hyphens are tricky. Within technical writing, hyphens connect words in certain compound terms, such as:
Self-attention
N-gram
Confusingly, three-word compound terms often contain a hyphen between the rst and second word but not between the second and third
word. For example:
Decision-making system
Floating-point feature
add_circle
When in doubt about hyphens, consult a dictionary, glossary, or style guide.
Note: If you consult more than one dictionary, glossary, or style guide about hyphens, you may encounter inconsistencies.
Colons In technical writing, use a colon to alert readers that a list or table will follow. In other words, terminate the sentence that introduces a list
or table (/tech-writing/one/lists-and-tables#introduce_each_list_and_table) with a colon. In the following example, notice the colon at the end of
the sentence that introduces the list:
Consider the following important programming languages:
Python
Java
C++
Technical writing prefers bulleted lists or numbered lists to embedded lists. That said, you can use a colon to introduce an embedded list
as in the following example:
Consider the following important programming languages: Python, Java, and C++.
Not all embedded lists require a colon. For example:
My three favorite programming languages are Python, Java, and anything other than C++.
Parentheses 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.
For example:
(Incidentally, Protocol Buffers make great birthday gifts.)
Binary mode relies on the more compact native form (described later in this document).
Next unit: Markdown (/tech-writing/one/markdown)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2025-02-04 UTC. Self-editing
Estimated Time: 10 minutes
Imagine that you just wrote the rst draft of a document. How do you make it better? In most cases, working towards a nal published
document is an iterative process. Transforming a blank page into a rst draft is often the hardest step. After you write a rst draft, make
sure you set aside plenty of time to re ne your document.
The editing tips in this unit can help turn your rst draft into a document that more clearly communicates the information your audience
needs. Use one tip or use them all; the important thing is to nd a strategy that works for you, and then make that strategy part of your
writing routine.
Note: The tips in this unit build on the basic writing and editing skills from Technical Writing One. This unit includes a summary of useful editing techniques
from that course. For a more detailed refresher, visit the self-study units (/tech-writing/one) from Technical Writing One.
Adopt a style guide Companies, organizations, and large open source projects frequently either adopt an existing style guide for their documentation or write
their own. Many of the documentation projects on the Google Developers (/) site follow the Google Developer Documentation Style Guide
(/style). If you've never relied on a style guide before, at rst glance the Google Developer Documentation Style Guide might seem a little
intimidating, offering detailed guidance on topics such as grammar, punctuation, formatting, and documenting computer interfaces. You
might prefer to start by adopting the style-guide highlights (/style/highlights).
Note: For smaller projects, such as team documentation or a small open source project, you might nd the highlights are all you need.
Some of the guidelines listed in the highlights are covered in Technical Writing One. You might recall some of the following techniques:
Use active voice (/tech-writing/one/active-voice) to make clear who's performing the action.
Format sequential steps as numbered lists (/tech-writing/one/lists-and-tables).
Format most other lists as bulleted lists.
The highlights introduce many other techniques that can be useful when writing technical documentation, such as:
Write in the second person (/style/person). Refer to your audience as "you", not "we".
Place conditions before instructions (/style/sentence-structure), not after.
Format code-related text as code font (/style/code-in-text).
Think like your audience Who is your audience? Step back and try to read your draft from their point of view. Make sure the purpose of your document is clear, and
provide de nitions for any terms or concepts that might be unfamiliar to your readers.
It can be helpful to outline a persona for your audience. A persona can consist of any of the following attributes:
A role, such as Systems Engineer or QA Tester.
An end goal, such as Restore the database.
A set of assumptions about the persona and their knowledge and experience. For example, you might assume that your persona is:
Familiar with Python.
Running a Linux operating system.
Comfortable following instructions for the command line.
You can then review your draft with your persona in mind. It can be especially useful to tell your audience about any assumptions you've
made. You can also provide links to resources where they can learn more if they need to brush up on a speci c topic.
Note that relying too heavily on a persona (or two) can result in a document that is too narrowly focused to be useful to the majority of
your readers.
For a refresher and more information on this topic from Technical Writing One, see the Audience (/tech-writing/one/audience) self-study unit.
Read it out loud
Depending on the context, the style of your writing can alienate, engage, or even bore your audience. The desired style of a given
document depends to an extent on the audience. For example, the contributor guide for a new open source project aimed at recruiting
volunteers might adopt a more informal and conversational style, while the developer guide for a commercial enterprise application might
adopt a more formal style.
To check if your writing is conversational, read it out loud. Listen for awkward phrasing, too-long sentences, or anything else that doesn't
feel natural. Alternatively, consider using a screen reader (https://en.wikipedia.org/wiki/Screen_reader) to voice the content for you.
For more information on adjusting the style of your writing to suit your audience, see Style and authorial tone (/style/tone).
Come back to it later
After you write your rst draft (or second or third), set it aside. Come back to it after an hour (or two or three) and try to read it with fresh
eyes. You'll almost always notice something that you could improve.
Change the context
Some writers like to print their documentation and review a paper copy, red pencil in hand. A change of context when reviewing your own
work can help you nd things to improve. For a modern take on this classic tip, copy your draft into a different document and change the
font, size, and color.
Find a peer editor
Just as engineers need peers to review their code, writers need editors to give them feedback on docs. Ask someone to review your
document and give you speci c, constructive comments. Your peer editor doesn't need to be a subject matter expert on the technical topic
of your document, but they do need to be familiar with the style guide you follow.
Exercise
If you have a document that you're working on, use one or more of the tips on this page to make it better. If you don't have a document in
progress, edit the paragraph below.
Determine whether or not you can simplify your document through the use of terminology that is equivalent but relatively shorter in
length and therefore more easily comprehensible by your audience. It's important to make sure your document is edited before it is seen
by your audience, which might include people that are less or more familiar with the matter covered by your document. The rst thing
you need is a rough draft. Some things that can help make your document easier to read are making sure you have links to background
information, and also checking for active voice instead of passive voice. If you have long sentences you can consider shortening them
or implementing the use of a list to make the information easier to scan.
Click the icon to see the answer.
To help your audience understand your document, apply these basic editing principles:
Use active voice instead of passive voice.
add_circle Consider using simpler words that mean the same thing.
Include links to background information.
Break long sentences into shorter sentences or lists.
Next unit: Organizing large documents (/tech-writing/two/large-docs)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Short sentences
Estimated Time: 20 minutes
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
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. For example, the following very long sentence contains multiple thoughts:
The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp
the following year, which gave programmers both an iterative way of solving problems and a recursive way.
Breaking the long sentence into a succession of single-idea sentences yields the following result:
The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following
year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.
Exercise
Convert the following overly long sentence to a series of shorter sentences. Don't revise too much; just end up with a few sentences
instead of only one.
In bash, use the if, then, and statements to implement a simple conditional branching block in which the if statement evaluates an
expression, the then statement introduces a block of statements to run when the if expression is true, and the statement marks the
end of the conditional branching block.
Click the icon to see the answer.
In bash, use anif, then, and fi statement to implement a simple conditional branching block. The if statement evaluates an
expression. The then statement introduces a block of statements to run when the if expression is true. The fi statement marks the end
of the conditional branching block. (The resulting paragraph remains unclear but is still much easier to read than the original sentence.)
Convert some long sentences to lists
Inside many long technical sentences is a list yearning to break free. For example, consider the following sentence:
add_circle To alter the usual ow of a loop, you may use either a break statement (which hops you out of the current loop) or a continue statement
(which skips past the remainder of the current iteration of the current loop).
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. For example, the preceding
example contains the conjunction or, so let's convert that long sentence to the following bulleted list:
To alter the usual ow of a loop, call one of the following statements:
break, which hops you out of the current loop.
continue, which skips past the remainder of the current iteration of the current loop.
Exercise
Refactor the following sentences into something shorter and clearer. Make sure that your answer contains a list:
1. To get started with the Frambus app, you must rst nd the app at a suitable store, pay for it using a valid credit or debit card,
download it, con gure it by assigning a value for the Foo variable in the /etc/Frambus le, and then run it by saying the magic word
twice.
2. KornShell was invented by David Korn in 1983, then a computer scientist at Bell Labs, as a superset of features, enhancements, and
improvements over the Bourne Shell (which it was backwards compatible with), which was invented by Stephen Bourne in 1977 who
was also a computer scientist at Bell Labs.
Click the icon to see the answer.
Sentence 1
Take the following steps to get started with the Frambus app:
1. Find the app at a suitable store.
2. Pay for the app using a valid credit or debit card.
3. Download the app.
4. Con gure the app by assigning a value for the Foo variable in the /etc/Frambus le.
5. Run the app by saying the magic word twice.
Sentence 2
The following two Bell Labs computer scientists invented popular shells:
Stephen Bourne invented the Bourne Shell in 1977.
David Korn invented the KornShell in 1983.
The KornShell is a backwards-compatible superset of the Bourne Shell, containing many improvements over the older shell.
Eliminate or reduce extraneous words
Many sentences contain ller—textual junk food that consumes space without nourishing the reader. For example, see if you can spot the
unnecessary words in the following sentence:
An input value greater than 100 causes the triggering of logging.
Replacing causes the triggering of with the much shorter verb triggers yields a shorter sentence:
add_circle An input value greater than 100 triggers logging.
With practice, you'll spot the extra words and feel enormous happiness in removing or reducing them. For example, consider the following
sentence:
This design document provides a detailed description of Project Frambus.
The phrase provides a detailed description of reduces to the verb describes (or the verb details), so the resulting sentence could become:
This design document describes Project Frambus.
The following table suggests replacements for a few common bloated phrases:
Wordy Concise
at this point in time now
determine the location of nd
is able to can
Exercise
Shorten the following sentences without changing their meaning:
1. In spite of the fact that Arnold writes buggy code, he writes error-free documentation.
2. Changing the sentence from passive voice to active voice enhances the clari cation of the key points.
3. Determine whether Rikona is able to write code in COBOL.
4. Frambus causes the production of bugs, which will be chronicled in logs by the LogGenerator method.
Click the icon to see the answer.
Here are some possible solutions:
1. Although Arnold writes buggy code, he writes error-free documentation.
Alternative answer: Arnold writes buggy code. However, he writes error-free documentation.
2. Changing the sentence from passive voice to active voice clari es the key points.
3. Determine whether Rikona can code in COBOL.
4. Frambus produces bugs, which the LogGenerator method logs.
Reduce subordinate clauses (optional)
A clause is an independent logical fragment of a sentence, which contains an actor and an action. Every sentence contains the following:
A main clause
Zero or more subordinate clauses
Subordinate clauses modify the idea in the main clause. As the name implies, subordinate clauses are less important than the main
clause. For example, consider the following sentence:
Python is an interpreted programming language, which was invented in 1991.
Main clause: Python is an interpreted programming language
Subordinate clause: which was invented in 1991
add_circle You can usually identify subordinate clauses by the words that introduce them. The following list (by no means complete) shows common
words that introduce subordinate clauses:
which
that
because
whose
until
unless
since
Some subordinate clauses begin with a comma and some don't. The highlighted subordinate clause in the following sentence, for
example, begins with the word because and does not contain a comma:
I prefer to code in C++ because I like strong data typing.
When editing, scrutinize subordinate clauses. Keep the one sentence = one idea, single-responsibility principle
(https://en.wikipedia.org/wiki/Single-responsibility_principle) in mind. Do the subordinate clauses in a sentence extend the single idea or do they
branch off into a separate idea? If the latter, consider dividing the offending subordinate clause(s) into separate sentences.
Exercise
Determine which of the sentences contain subordinate clauses that should be branched off into separate sentences. (Don't rewrite the
sentences, just identify the sentences that should be rewritten.)
1. Python is an interpreted language, which means that the language can execute source code directly.
2. Bash is a modern shell scripting language that takes many of its features from KornShell 88, which was developed at Bell Labs.
3. Lisp is a programming language that relies on Polish pre x notation, which is one of the systems invented by the Polish logician Jan
Łukasiewicz.
4. I don't want to say that Fortran is old, but only radiocarbon dating can determine its true age.
Click the icon to see the answer.
We've shaded the subordinate clauses.
1. Python is an interpreted language, which means that the language can execute source code directly. The subordinate clause in this
sentence extends the main idea, so this sentence is ne as is.
2. Bash is a modern shell scripting language that takes many of its features from KornShell 88, which was developed at Bell Labs. The
rst subordinate clause extends the main idea, but the second subordinate clause goes in another direction. Divide this sentence
in two.
3. Lisp is a programming language that relies on Polish pre x notation, which is one of the systems invented by the Polish logician Jan
Łukasiewicz. The rst subordinate clause is clearly critical to the sentence, but the second subordinate clause takes the reader too
far away from the main clause. Divide this sentence in two.
4. I don't want to say that Fortran is old, but only radiocarbon dating can determine its true age. The subordinate clause is critical to
the sentence, so this sentence is ne as is.
Distinguish that from which
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.
add_circle 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. For example, the key message in the following sentence is that Python is an interpreted language; the
sentence can survive without Guido van Rossum invented:
Python is an interpreted language, which Guido van Rossum invented.
By contrast, the following sentence requires don't involve linear algebra:
Fortran is perfect for mathematical calculations that don't involve linear algebra.
If you read a sentence aloud and hear a pause just before the subordinate clause, then use which. If you don't hear a pause, use that. Go
back and read the preceding two example sentences. Do you hear the pause in the rst sentence?
Place a comma before which; do not place a comma before that.
Next unit: Lists and tables (/tech-writing/one/lists-and-tables)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Summary of Technical Writing One Estimated Time: 1 minute
Technical Writing One covered the following basic lessons of technical writing:
Use terms consistently.
Avoid ambiguous pronouns.
Prefer active voice to passive voice.
Pick speci c verbs over vague ones.
Focus each sentence on a single idea.
Convert some long sentences to lists.
Eliminate unneeded words.
Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant.
Keep list items parallel.
Start numbered list items with imperative words.
Introduce lists and tables appropriately.
Create great opening sentences that establish a paragraph's central point.
Focus each paragraph on a single topic.
Determine what your audience needs to learn.
Fit documentation to your audience.
Establish your document's key points at the start of the document.
Congratulations! You've completed the pre-class portion of Technical Writing One.
The in-class component of Technical Writing One helps you practice technical writing principles:
If your organization offers the in-class portion of Technical Writing One, you are now ready for that class.
If your organization doesn't offer the in-class portion of Technical Writing One, consider joining one of the free public courses listed
on the Announcements page (/tech-writing/announcements).
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Summary of Technical Writing Two
Estimated Time: 1 minute
Technical Writing Two covered the following intermediate lessons of technical writing:
Adopt a style guide.
Think like your audience.
Read documents out loud (to yourself).
Return to documents well after you've written the draft.
Find a good peer editor.
Outline a document. Alternatively, write free form and then organize.
Introduce a document's scope and any prerequisites.
Prefer task-based headings.
Disclose information progressively (in some situations).
Consider writing the caption before creating the illustration.
Constrain the amount of information in a single drawing.
Focus the reader's attention on the relevant part of a picture or diagram by describing the takeaway in the caption or by adding a
visual cue to the picture.
Create concise sample code that is easy to understand.
Keep code comments short, but prefer clarity over brevity.
Avoid writing comments about obvious code.
Focus your commenting energy on anything non-intuitive in the code.
Provide not only examples but also anti-examples.
Provide code samples that demonstrate a range of complexity.
Make a practice of continuous revision.
Provide different documentation types for different categories of users.
Compare and contrast with something that readers are already familiar with.
In tutorials, reinforce concepts with examples.
In tutorials, note problems that readers may encounter.
Congratulations! You've completed the pre-class portion of Technical Writing Two.
The in-class component of Technical Writing Two helps you practice technical writing principles:
If your organization offers the in-class portion of Technical Writing Two, you are now ready for that class.
If your organization doesn't offer the in-class portion of Technical Writing Two, consider joining one of the free public courses listed
on the Announcements page (/tech-writing/announcements).
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Technical Writing One introduction Technical Writing One teaches you how to write clearer technical documentation.
Target audience You need at least a little writing pro ciency in English, but you don't need to be a strong writer to take this course.
If you've never taken any technical writing training, this course is perfect for you. If you've taken technical writing training, this class
provides an e cient refresher.
Learning objectives This course teaches you the fundamentals of technical writing. After completing this class, you will know how to do the following:
Use terminology—including abbreviations and acronyms—consistently.
Recognize ambiguous pronouns.
Distinguish active voice from passive voice.
Convert passive voice sentences to active voice.
Identify three ways in which active voice is superior to passive voice.
Develop at least three strategies to make sentences clearer and more engaging.
Develop at least four strategies to shorten sentences.
Understand the difference between bulleted lists and numbered lists.
Create helpful lists.
Create effective lead sentences for paragraphs.
Focus each paragraph on a single topic.
State key points at the start of each document.
Identify your target audience.
Determine what your target audience already knows and what your target audience needs to learn.
Understand the curse of knowledge.
Identify and revise idioms.
State your document's scope (goals) and audience.
Break long topics into appropriate sections.
Use commas, parentheses, colons, em dashes, and semicolons properly.
Develop beginner competency in Markdown.
It takes years of focused practice to become a great engineer or a great technical writer. This course will improve your technical writing
but will not instantly transform you into a great technical writer.
Pre-class and in-class components The course consists of the following two components:
Pre-class
In-class
You are currently viewing the start of the pre-class component.
The in-class component enhances the lessons taught in the pre-class components. That said, the pre-class lessons on their own still
provide a valuable educational experience.
Hardware and network requirements Although this course is optimized for a laptop or desktop, you may take the course on a tablet or phone. If you are taking the in-class
component, please note that you'll type a lot.
You need an internet connection to take the course. You cannot download the course. The course is not available on tangible media.
The course contains a few short videos, all of which are optional viewing. If you want to skip the videos, then you can take the course on a
low-bandwidth internet connection.
Optional units We've marked a few units as optional. This material isn't essential, though you'll probably nd the material useful.
Next unit: Just enough grammar (/tech-writing/one/just-enough-grammar), an optional unit
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Technical Writing Two introduction Technical Writing Two helps technical people improve their technical communication skills.
Target audience We've aimed this course at people who have completed Technical Writing One (/tech-writing/one) and are still hungry for more technical
writing training. If you've never taken any technical writing training, we recommend completing Technical Writing One before taking this
class.
Learning objectives This course focuses on several intermediate topics in technical writing. After completing this class, you will know how to do the following:
Choose among several different tactics to write rst drafts and additional tactics for writing second and third drafts.
Use several techniques to detect mistakes in your own writing.
Organize large documents.
Introduce a document's scope and any prerequisites.
Write clear gure captions.
Pick the proper information density in technical illustrations.
Focus the reader's attention in illustrations.
Establish context through a "big picture" illustration.
Revise technical illustrations effectively.
Create useful, accurate, concise, clear, reusable, and well-commented sample code that demonstrates a range of complexity.
Identify different documentation types.
Describe just about anything.
Empathize with a beginner audience and write a tutorial for them.
It takes years of focused practice to become a great engineer or a great technical writer. This course will improve your technical writing
but will not instantly transform you into a great technical writer.
Pre-class and in-class components The course consists of the following two components:
pre-class
in-class
You are currently viewing the start of the pre-class component.
The in-class component enhances the lessons taught in the pre-class components. That said, the pre-class lessons on their own still
provide a valuable educational experience.
Hardware and network requirements Although this course is optimized for a laptop or desktop, you may take the course on a tablet or phone. If you are taking the in-class
component, please note that you'll type a lot.
You need an internet connection to take the course. You cannot download the course. The course is not available on tangible media. The course contains a few short videos, all of which are optional viewing. If you want to skip the videos, then you can take the course on a
low-bandwidth internet connection.
Next unit: Self-editing (/tech-writing/two/editing)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC. Words Estimated Time: 10 minutes
We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words.
De ne new or unfamiliar terms 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. (Don't reinvent the wheel.)
If your document is introducing the term, de ne the term. If your document is introducing many terms, collect the de nitions into a
glossary.
Use terms consistently If you change the name of a variable midway through a method, your code won’t compile. Similarly, if you rename a term in the middle of a
document, your ideas won’t compile (in your users’ heads).
The moral: apply the same unambiguous word or term consistently throughout your document. Once you've named a component thingy,
don't rename it thingamabob. For example, the following paragraph mistakenly renames Protocol Buffers to protobufs:
Protocol Buffers provide their own de nition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.
George Fairbanks, a Google software engineer, provides this excellent note about consistent naming:
When I encounter two words that seem to be synonyms, I wonder if the author is trying to signal a subtle distinction that I need to track down and understand.
Yes, technical writing is cruel and restrictive, but at least technical writing provides an excellent workaround. 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. For example, the following paragraph is ne:
Protocol Buffers (or protobufs for short) provide their own de nition language. Blah, blah, blah. And that's why protobufs have won so
many county fairs.
Use acronyms properly 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. For 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 nger motions.
You may then use the acronym going forward, as in the following example:
If no cache entry exists, the Mixer calls the OttoGroup Server (OGS) to fetch Ottos for the request. The OGS is a repository that holds all
servable Ottos. The OGS is organized in a logical tree structure, with a root node and two levels of leaf nodes. The OGS root forwards
the request to the leaves and collects the responses.
Do not cycle back-and-forth between the acronym and the expanded version in the same document.
Use the acronym or the full term? Sure, you can introduce and use acronyms properly, but should you use acronyms? Well, acronyms do reduce sentence size. For example,
TTN is two words shorter than Telekinetic Tactile Network. However, acronyms are really just a layer of abstraction; readers must mentally
expand recently learned acronyms to the full term. For example, readers convert TTN to Telekinetic Tactile Network in their heads, so the
"shorter" acronym actually takes a little longer to process than the full term.
Heavily used acronyms develop their own identity. After a number of occurrences, readers generally stop expanding acronyms into the full
term. Many web developers, for example, have forgotten what HTML expands to.
Here are the guidelines for acronyms:
Don't de ne acronyms that would only be used a few times.
Do de ne acronyms that meet both of the following criteria:
The acronym is signi cantly shorter than the full term.
The acronym appears many times in the document.
Exercise
Fix the following passage. Assume that this passage is the initial instance of the term MapReduce in the document and that MR is the
best abbreviation.
Jeff Dean invented MapReduce in 1693, implementing the algorithm on a silicon-based computer fabricated from beach sand, wax-
paper, a quill pen, and a toaster oven. This version of MR held several world performance records until 2014.
(Please note that the preceding passage is meant to be humorous, not factual.)
Click the icon to see the answer.
You could take a few different approaches here. One approach is to associate the acronym MR with the full term and then use that
acronym:
Jeff Dean invented MapReduce (MR) in... This version of MR held several...
Alternatively, you could decide that de ning an acronym for such a short passage puts too much burden on readers, so you'll simply use
the full term MapReduce every time:
Jeff Dean invented MapReduce in... This version of MapReduce held several...
Incidentally, a more thorough technical writer would also convert "beach sand, wax-paper, a quill pen, and a toaster oven" into a bulleted
list. However, that's another story for another lesson.
Recognize ambiguous pronouns
Many pronouns point to a previously introduced noun. Such pronouns are analogous to pointers in programming. Like pointers in
programming, pronouns tend to introduce errors. Using pronouns improperly causes the cognitive equivalent of a null pointer error in your
readers’ heads. In many cases, you should simply avoid the pronoun and just reuse the noun. However, the utility of a pronoun sometimes
outweighs its risk (as in this sentence).
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 ve 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.
It and they
add_circle The following pronouns cause the most confusion in technical documentation:
It
They, them, and their
For example, in the following sentence, does It refer to Python or to C++?
Python is interpreted, while C++ is compiled. It has an almost cult-like following.
As another example, what does their refer to in the following sentence?
Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in their core may cause accidental mass
unfriending.
This and that
Consider two additional problem pronouns:
This
That
For example, in the following ambiguous sentence, This could refer to the user ID, to running the process, or to all of these:
Running the process con gures permissions and generates a user ID. This lets users authenticate to the app.
To help readers, avoid using this or that in ways where it's not clear what they refer to. Use either of the following tactics to clarify
ambiguous uses of this and that:
Replace this or that with the appropriate noun.
Place a noun immediately after this or that.
Substitute or add explicit terms as needed, as in the following rewrites of the example's second sentence:
This user ID lets users authenticate.
The process of con guring permissions lets users authenticate.
The combination of permissions and a user ID lets users authenticate.
Exercise
Identify all possible meanings for the ambiguous pronouns in each of the following passages:
1. Aparna and Phil share responsibilities with Maysam and Karan and they are next on call.
2. You may import Carambola data via your con guration le or dynamically at run time. This may be a security risk.
Click the icon to see the answer.
1. The pronoun they could refer to any of the following:
Aparna and Phil
Maysam and Karan
Aparna, Phil, Maysam, and Karan
Any one of the individuals as a singular gender-neutral pronoun (/style/pronouns#gender-neutral-pronouns)
2. The pronoun this could refer to any of the following:
Importing via the con guration le
Importing dynamically at run time
add_circle Both
Next unit: Active voice (/tech-writing/one/active-voice)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License (https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0). For details, see the Google Developers Site Policies
(https://developers.google.com/site-policies). Java is a registered trademark of Oracle and/or its a liates.
Last updated 2024-08-06 UTC.