# Technical Writing Courses

Every engineer is also a writer.

This collection of courses and learning resources aims to improve your technical documentation. Learn how to plan and author technical documents. You can also learn about the role of technical writers at Google.

# Overview of technical writing courses

The following table summarizes the technical writing courses:

Take this course… Title Focus Pre-Class In-Class
first Technical Writing One the critical basics of technical writing 2 hours 2 to 2.5 hours
second Technical Writing Two intermediate topics in technical writing 1 hour 2 to 2.5 hours

The pre-class components introduce topics; the in-class components help students integrate those topics. That said, the pre-class lessons on their own still provide a valuable educational experience.

We’ve aimed Technical Writing One and Technical Writing Two at the following audiences:

• software engineers
• software engineering students

Additionally, many people in engineering-adjacent roles (such as product managers) have also benefited from these courses.

# Technical Writing One

## Technical Writing One introduction

Technical Writing One teaches you how to write clearer technical documentation.

#### Target audience

You need at least a little writing proficiency 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 efficient 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 and disambiguate pesky 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 effective lead sentences for paragraphs.
• Focus each paragraph on a single topic.
• State key points at the start of each document.
• 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 find the material useful.

## Just enough grammar (optional)

This unit provides just enough grammar to understand the remainder of the course. If you already know some grammar, move on to 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 Definition Example
Noun a person, place, concept, or thing Sam runs races.
Pronoun a noun that substitutes for another noun Sam runs races. He likes to compete.
Adjective a word or phrase that modifies a noun Sam wears blue shoes.
Verb an action word or phrase Sam runs races.
Adverb a word or phrase that modifies 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 finishes 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. For example, we’ve highlighted the nouns in the following passage:

In the framework, an object must copy any underlying values that the object wants to change. The protos in the codebase are huge, so copying the protos 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.

You can find 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 first sentence is a verb. Many words in English serve as a noun in some contexts and a verb in others.

### 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 first sentence establishes Janet as a noun. The second sentence substitutes the pronoun She for the noun Janet.

In the following example, the pronoun This substitutes for the entire sentence that preceded it:

Most applications aren’t sufficiently tested. This is poor engineering.

#### Exercise

Identify the three pronouns in the following passage:

The cafeteria featured peashew butter and pluot jam on pumperye toast. Employees found it awesome and wished they could eat this every day.

The cafeteria featured peashew butter and pluot jam on pumperye 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 identifies 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.
• Chung likes snacks to eat while riding the train.

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.

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 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 fixed eight bugs at work.

Most adverbs modify verbs. For example, notice how the adverb (efficiently) in the following sentence modifies the verb (fixes):

• Jane efficiently fixes bugs.

Adverbs are not necessarily right next to their verb. For example, in the following sentence, the adverb (efficiently) is two words away from the verb (fixes):

• Jane fixes bugs efficiently.

#### Exercise

Identify the four adjectives in the following passage:

Engineering is a great career for brilliant minds. I know five engineers who could excel at any intellectual task.

Engineering is a great career for brilliant minds. I know five engineers who could excel at any intellectual task.

### 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 first half of the sentence with the second.

Natasha 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 sufficient 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 first line of code. _____________, she spontaneously coded a method the other day when she was suddenly inspired.

The best transition for this situation is as follows:

However

## Words

We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words.

### Define 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, define the term. If your document is introducing many terms, collect the definitions 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 definition language. Blah, blah, blah. And that’s why protobufs have won so many county fairs.

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 fine:

Protocol Buffers (or protobufs for short) provide their own definition 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 finger 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 define acronyms that would only be used a few times.
• Do define acronyms that meet both of the following criteria:
• The acronym is significantly shorter than the full term.
• The acronym appears many times in the document.

#### 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. His version of MR held several world performance records until 2014.

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 defining 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.

### Disambiguate 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. Improperly using pronouns causes the cognitive equivalent of a nullptr 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. As a rule of thumb, if more than five words separate your noun from your pronoun, consider repeating the noun instead of using the pronoun.

#### It and they

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

• this
• that

For example, in this following ambiguous sentence, This could refer to Frambus, to Foo, or to both:

You may use either Frambus or Foo to calculate derivatives. This is not optimal.

Use either of the following tactics to disambiguate this and that:

• Replace this or that with the appropriate noun.
• Place a noun immediately after this or that.

For example, either of the following sentences disambiguate the previous example:

Overlapping functionality is not optimal.

This overlapping functionality is not optimal.

#### 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 the next ones on call.
2. You may import Carambola data via your configuration file or dynamically at run time. This may be a security risk.
1. The pronoun they could refer to any of the following:
• Aparna and Phil
• Maysam and Karan
• Aparna, Phil, Maysam, and Karan
2. The pronoun this could refer to any of the following:
• importing via the configuration file
• importing dynamically at run time
• both

## Active voice vs. passive voice

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 rolling1:

https://youtu.be/nG6DhoFt938

### Distinguish active voice from passive voice in simple sentences

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

#### Active voice example

For example, here’s a short, active voice sentence:

The cat sat on the mat.

• actor: The cat
• verb: sat
• target: the mat

#### Passive voice examples

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.

### Recognize passive verbs

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 does not 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

#### Imperative verbs are typically active

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:

1. Open the configuration file.
2. Set the Frombus variable to False.

Sentences that start with an imperative verb are typically in active voice, even though they do not explicitly mention an actor. Instead, sentences that start with an imperative verb imply an actor. The implied actor is you.

#### Exercise

Mark each of the following sentences as either Passive or Active:

1. MutableInput provides read-only access.
2. Read-only access is provided by MutableInput.
3. Performance was measured.
4. Python was invented by Guido van Rossum in the twentieth century.
5. David Korn discovered the KornShell quite by accident.
6. This information is used by the policy enforcement team.
7. Click the Submit button.
8. The orbit was calculated by Katherine Johnson.
1. Active. MutableInput provides read-only access.
2. Passive. Read-only access is provided by MutableInput.
3. Passive. Performance was measured.
4. Passive. Python was invented by Guido van Rossum in the twentieth century.
5. Active. David Korn discovered the KornShell quite by accident.
6. Passive. This information is used by the policy enforcement team.
7. Active. Click the Submit button. (Click is an imperative verb.)
8. Passive. The orbit was calculated by Katherine Johnson.

### Distinguish active voice from passive voice in more complex sentences

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 voice:

Here is that same sentence, partially converted to active voice:

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 first verb is active and the second is passive, write Active, Passive.

1. The QA team loves ice cream, but their managers 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.
1. Active, Active. The QA team loves ice cream, but their managers 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, readers can 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.

#### Scientific research reports (optional material)

The writing in research reports tends to be understated. Here, for example, is one of the most famous passages in twentieth century science writing, from Crick and Watson’s 1953 paper in Nature entitled, Molecular Structure of Nucleic Acids: A Structure for Deoxyribose Nucleic Acid:

It has not escaped our notice that the specific pairing we have postulated immediately suggests a possible copying mechanism for the genetic material.

The authors are so excited about their discovery that they’re whispering it from the rooftops.

Passive voice thrives in a tentative landscape. In 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 scientific journals have embraced active voice. We encourage the remainder to join the quest for clarity.

#### 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 flags were not parsed by the Mungifier.
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 identified by asterisks; ampersands identify bad metrics.
1. The Mungifier did not parse the flags.
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.

## 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, specific 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 error occurs when clicking the Submit button. Clicking the Submit button triggers the error.
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 specific 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.
• 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.
• 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.

### 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 still 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:

#### 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.
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.

Setting this flag 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 flag 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 believability.

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.

## 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 fi 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 fi statement marks the end of the conditional branching block.

In bash, use an if, 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:

To alter the usual flow 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 flow 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 first find the app at a suitable store, pay for it using a valid credit or debit card, download it, configure it by assigning a value for the Foo variable in the /etc/Frambus file, 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.

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.
4. Configure the app by assigning a value for the Foo variable in the /etc/Frambus file.
5. Run the app by saying the magic word twice.

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’s features are a backwards-compatible superset of the Bourne Shell’s.

### Eliminate or reduce extraneous words

Many sentences contain filler—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:

An input value greater than 100 triggers logging.

With practice, you’ll spot the extraneous words and take inordinate glee 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 details, so the resulting sentence becomes:

This design document details 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 find
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 clarification 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.

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 clarifies 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

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 formula 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 prefix 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.

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 fine 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 first 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 prefix notation, which is one of the systems invented by the Polish logician Jan Łukasiewicz. The first 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 fine 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 American readers will angrily announce that you confused the two words again.

In America, reserve which for subordinate clauses that are nonessential parts of the sentence, and use that for an essential phrase that the sentence can’t live without. For example:

Python is an interpreted language, which means the processor runs the program directly.

FORTRAN is perfect for mathematical calculations that don’t involve linear algebra.

Was that explanation useful? Probably not. Try this instead: 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 two example sentences. Did you hear the pause in the first sentence?

Place a comma before which; do not place a comma before that.

## 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 file 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 reconfigure the server:

1. Stop the server.
2. Edit the configuration file.
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 vicugnas, 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 vicugnas.
• 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).

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), lower case (capitalization), and without periods or commas (punctuation).

• carrots
• potatoes
• cabbages

By contrast, the following list is painfully nonparallel along all four 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 first 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.

The list is nonparallel. The first 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.

This is a nonparallel list. The first 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:

2. Configure 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.

#### Exercise

Make the following list parallel. Ensure that each element in the result list begins with an imperative verb:

1. Stop Früvous
2. The key configuration file is /moxy/fruvous. Open this file with an ASCII text editor.
3. In this file, 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 finished setting this parameter, save and close the configuration file
5. now, start Früvous again.

The following is one possible answer:

1. Stop Früvous.
2. Open the key configuration file, /moxy/fruvous, with an ASCII text editor.
3. Change the Carambola parameter from its default value (32) to 64.
4. Save and close the configuration file.
5. Restart Früvous.

Punctuate items appropriately

If the list item is a sentence, use sentence capitalization and punctuation. Otherwise, do not use sentence capitalization and punctuation. For example, the following list item is a sentence, so we capitalized the M in Mostand put a period at the end of the sentence:

• Most carambolas have five ridges.

However, the following list item is not a sentence, so we left the t in the in lowercase and omitted a period:

• the color of lemons

###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 elephants.

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.

### 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 identifies 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:

Languages Inventor Year Introduced Key Feature
Lisp John McCarthy 1958 recursion
C++ Bjarne Stroustrup 1979 OOP
Python Guido van Rossum 1994 simplicity

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 identifies the inventor, year of invention, and key feature of three popular programming languages:

## Paragraphs

Estimated Time: 10 minutes

This unit provides some guidelines on building cohesive paragraphs. But first, 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.

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.

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 fifth 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.

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 five sentences, but will avoid paragraphs containing more than about seven sentences. When revising, consider dividing very long paragraphs into two separate paragraphs.

Conversely, don’t make paragraphs too short. If your document contains plenty of one-sentence paragraphs, your organization is faulty. Seek ways to combine those one-sentence paragraphs into cohesive multi-sentence paragraphs or possibly into lists.

### Answer what, why, and how

Good paragraphs answer the following three questions:

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:

<Start of What> The garp() function returns the delta between a dataset’s mean and median.<End of What> <Start of Why>Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily influenced by a few very large or very small data points. <End of Why> <Start of How>Call garp() to help determine whether a few very large or very small data points are influencing the mean too much. A relatively small garp() value suggests that the mean is more meaningful than when the garp() value is relatively high.<End of How>

## 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 your audience needs that your audience doesn’t already have. Therefore, this unit explains how to do the following:

• Determine what your audience needs to learn.
• Fit documentation to your audience.

As the following video suggests, targeting the wrong audience can be messy: https://youtu.be/eFtXIrmsMwI

Serious documentation efforts spend considerable time and energy on defining 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 scientific fields (for example, physicians)
• non-technical positions

We happily appreciate that many people in non-technical roles have great technical and mathematical skills. However, roles remain an essential first-order approximation in defining your audience. People within the same rolegenerally share certain base skills and knowledge. For example:

• Most software engineers know popular sorting algorithms, 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 first-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 insufficient for defining 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 fictitious 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 specific 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 unselfish empathy. You must create explanations that satisfy your audience’s curiosity rather than your own. How do you step out of yourself in order to fit documentation to the audience? Unfortunately, we can offer no easy answers. We can, however, offer a few parameters to focus on.

#### Vocabulary and concepts

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 specifically 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 fine-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.

1. 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?
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, English is not the native language of a significant percentage of technical readers. Therefore, prefer simple words over complex words. Avoid using arcane, obsolete, or overly-complex English words; sesquipedalian and rare words repel most 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:

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

Cake? Bob? Most American readers recognize the first idiom; most British readers recognize the second idiom. If you are writing strictly for a British audience, then Bob’s your uncle can be fine. However, if you are writing for an international audience, then replace that idiom with this task is easy.

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 BorgResourceSpec constraints/preferences are combinable is a sticky wicket.
3. Be that as it may, you still have to write unit tests.
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 fix this issue.
3. Be that as it may is an idiom. Substituting the transition However will fix this problem.

## Documents

Estimated Time: 10 minutes

You can write sentences. You can write paragraphs. However, can you organize all those paragraphs into a coherent document?

A good document begins by defining its scope. For example:

This document describes the overall design of Project Frambus.

A better document additionally defines its non-scope, that is, the topics not covered that the target audience might expect your document to cover. For example:

This document does not describe the design for the related technology, Project Froobus.

These scope and non-scope statements benefit not only the reader but also the writer (you). While writing, if the contents of your document veer away from the scope statement, then you must either refocus your document or modify your scope statement. When reviewing your first draft, delete (or branch off to another document) any sections that don’t help satisfy the scope statement.

A good document explicitly specifies its audience. For example:

I wrote this document for the test engineers supporting Project Frambus.

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 how to brew a really good cup of tea.

In some cases, the audience declaration must also specify prerequisite documents. For example:

You must read “Project Froobus: A New Hope” prior to reading this document.

### Establish your key points up front

Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, page one of any long document is the hardest page to write. Therefore, be prepared to revise page one many times.

Always write an executive summary (a TL;DR) for long engineering documents. Although the executive summary must be very short, expect to spend a lot of time writing it. A boring or confusing executive summary is a red flag warning potential readers to stay away.

This course repeatedly emphasizes the importance of defining your audience. In this section, we focus on audience definition as a means of organizing your document.

#### Define audience

Answering the following questions helps you determine what your document should contain:

• Who is your target audience?

For example, suppose you have invented a new sorting algorithm. The following list contains some potential answers to the preceding questions:

• My target audience consists of all the software engineers in my organization.
• Most of my target audience studied sorting algorithms during school. However, about 25% of my target audience hasn’t implemented or evaluated a sorting algorithm in many years.
1. Readers know how the algorithm works.
2. Readers can implement the algorithm in their desired language.
3. Readers know the circumstances in which the algorithm outperforms the popular quicksort algorithm.

#### Organize

After defining the audience, organize the document to supply what readers should know or be able to do after reading the document. For example, the outline for the document could look as follows:

1. Overview of the algorithm
1. Big O
2. Implementation in pseudocode
2. Sample implementation in C
1. Tips in implementing in other languages
3. Deeper analysis of algorithm
1. Optimal datasets
2. Edge case problems

Furthermore, use the audience definition to help you choose the right approach to writing your document. For example, the target audience studied sorting algorithms but about a quarter of your audience might not remember the details of different algorithms. Therefore, your document should probably insert links to existing tutorials on quicksort rather than trying to explain quicksort.

### Break your topic into sections

You modularize code into files, classes, and methods. Modular code is easier to read, understand, maintain, and reuse. Making your doc modular gives you the same benefits. You probably have strong intuition about functional modularity in code, but how do you apply those principles to your writing?

Imagine that you have an empty jar, which you need to pack with a collection of large rocks, coarse gravel, and sand. How would you pack the jar to ensure that you can get all of your material in the jar? Of course you’d place the large rocks first, then pour in the gravel, and fill in the remaining air space with the sand. If you tried to do this in the opposite order, you would fail.

Your reader’s head is much like an empty jar, and your information generally comes in three sizes: rocks, gravel, and sand. Sections are the rocks. You need to structure the space inside your reader’s jar-head with the rocks to accept the rest of the information.

But how do you decide what is a big rock versus what is gravel? One strategy is to record yourself talking, or free-write, about your topic for a short amount of time—maybe just 2 to 5 minutes. Yes, this takes discipline. Examine what you produced. Did you do the following?

• Describe concepts in vague, under-specified ways?
• List the steps that your audience needs to complete to reach a goal?
• Describe the permutations of properties that a system can express?

The under-specified things that you referred to are probably the large concepts that structure your topic. If your talk didn’t do this, go back and try this structure.

#### Exercise

The following passage is the introductory paragraph for a document. List the titles of the sections that you would break this topic into.

AlienWarez is a large-scale machine learning system. AlienWarez is best at building models for high-dimensional, sparse feature spaces. AlienWarez automatically explores and learns feature crosses that explain your data. AlienWarez refers specifically to the model training system. You train a model by extracting features from your source (log) data, and writing a data source for the training system. The Seti infrastructure team also provides a complete serving system. You are responsible for starting your own serving cluster, and moving your model to serving. The Seti serving system can serve AlienWarez, Seti, and Sibyl models. This guide explains how to train a AlienWarez model, and how to serve the model in production.

Here is a possible outline:

1. Training a model
1. Developing features
2. Creating a data source
2. Serving a model
1. Starting a serving cluster
2. Moving your model into serving
3. Retrieving a prediction from serving

## 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 rest, then a comma is perhaps a half-note or quarter-note 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 briefly 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 final 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 final 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 flag.

If the program runs slowly, then try the --perf flag.

You can also wedge a quick definition or digression between a pair of commas as in the following example:

Python, an easy-to-use language, has gained significant 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:

Samantha is a wonderful coder, she writes abundant tests.

Use a period rather than a comma to separate two independent thoughts. For example:

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 efficiently which has led to rapid adoption.

Hint: Read the passage aloud and put a comma everywhere you hear a short pause.

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 efficiently, 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 first and second thoughts:

Rerun Frambus after updating your configuration file; don’t rerun Frambus after updating existing source code.

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 not a complete sentence:

Rerun Frambus after updating your configuration file; not after updating existing source code.

Before using a semicolon, ask yourself whether the sentence would still make sense if you flipped 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 configuration file.

You should almost always use commas, not semicolons, to separate items in an embedded list. For example, the following use of semicolons is incorrect:

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 official 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.

#### Exercise

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.
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. If a comma is a quarter note rest, then an em-dash is a half-note rest. For example:

C++ is a rich language—one requiring extensive experience to master.

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 efficient 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. Remember—punctuation in English is squishy and malleable.

### Parentheses

Use parentheses to hold minor points and digressions. Parentheses inform readers that the enclosed text isn’t critical.

The rules regarding periods and parentheses have tripped up many a writer. Here are the standards:

• 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).

## 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 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.


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 files into HTML. Browsers can then display the resulting HTML to readers.

We recommend becoming comfortable with Markdown by taking one of the following tutorials:

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, please take it.

A quick compilation of the topics covered in Technical Writing One is available on the Summary page.

## Summary of Technical Writing One

Technical Writing One covered the following basic lessons of technical writing:

• Use terms consistently.
• Avoid ambiguous pronouns.
• Prefer active voice to passive voice.
• Choose strong verbs.
• Pick specific nouns 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.

As time permits, consider reviewing these additional technical writing resources.

# Technical Writing Two

## 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 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 first drafts and additional tactics for writing second and third drafts.
• Leverage several techniques to detect mistakes in your own writing.
• Organize large documents.
• Introduce a document’s scope and any prerequisites.
• Write clear figure 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.
• 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.

## Self-editing

Estimated Time: 10 minutes

Imagine that you just wrote the first draft of a document. How do you make it better? In most cases, working towards a final published document is an iterative process. Transforming a blank page into a first draft is often the hardest step. After you write a first draft, make sure you set aside plenty of time to refine your document.

The editing tips in this unit can help turn your first 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 find 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 from Technical Writing One.

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 theGoogle Developer Documentation Style Guide. If you’ve never relied on a style guide before, at first 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 thestyle-guide highlights.

Note: For smaller projects, such as team documentation or a small open source project, you might find 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 to make clear who’s performing the action.
• Format sequential steps as numbered lists.
• Format most other lists as bulleted lists.

The highlights introduce many other techniques that can be useful when writing technical documentation, such as:

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 definitions 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 specific 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 self-study unit.

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 your writing is conversational, read it out loud. Listen for awkward phrasing, too-long sentences, or anything else that doesn’t feel natural. Alternatively, you can also try asking someone else to read your draft out loud for you.

### Come back to it later

After you write your first 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 find 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 specific, 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 first 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.

• Use active voice instead of passive voice.
• Consider using simpler words that mean the same thing.
• Include links to background information.
• Break long sentences into shorter sentences or lists.

## 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:

• Organizing a document
• 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 finds reading long documents difficult and disorientating. He prefers to use site search to find answers to his questions.
• Rose is comfortable navigating large documents. She often uses the built-in page search feature in her web browser to find 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 benefit 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 flag.

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 first 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 find 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 find 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 the browser plugin; explain that we’ll use the results of the audit report to fix 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 specific 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.
• Documents that alternate between conceptual information and practical steps can be a particularly engaging way to learn. Consider explaining a concept and then demonstrating how the reader can apply it in either a sample project or in their own work.
• Outlines are especially useful if you’re working with a team of contributors who are going to review and test your document. Before you start drafting, share your outline with your contributors to check if they have any suggestions.

#### Outline exercise

For this exercise, review and update the following high-level outline of an introduction to a long tutorial. You can rearrange, add, and remove topics.

## 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

## 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.


The following is one possible solution:

## Audience

Describes who the tutorial is aimed at.

## Prerequisites

Lists concepts the reader should be familiar with prior to starting, as well as
any software or hardware requirements.

## Setting up the tutorial

## Useful terminology

Lists definitions of terms that the reader needs to know to follow the
tutorial.


#### Introduce a document

If readers of your documentation can’t find 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 first 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 find 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 and run the F@ command-line linter 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.


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 and run the F@ command-line
linter on your code. If you have suggestions for additions to the list of best
practices, file an issue in the F@ documentation repository.


Providing navigation and signposting for your readers ensures they can find what they are looking for and the information they need to get unstuck.

• introduction and summary sections
• a clear, logical development of the subject
• overviews that introduce the tool
• links to related resources or more in-depth information
• links to what to learn next

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 first 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

To create the site, you run the carambola command-line tool. The command

### Running the carambola command


For this exercise, improve the following outline. You can rearrange, add, and delete topics and create secondary entries too.

About this tutorial
Define resource paths
Defining and building projects
Launch the development environment
Defining and building resources
What's next
Define image resources
Audience
Build an image resource
Define an image project
Build an image project
Setting up the tutorial
Select the tutorial asset root


The following is one possible solution:

## About this tutorial

### Audience

## 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

### Define a database

### Build a database

## Pushing, publishing, and viewing a database

### Push a database

### Publish a database

### View a database

## Configuring display rules for point data

### Define, configure, and build vector data

### Sample data files

## What's next


### 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 to 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.

## Illustrating

Estimated Time: 10 minutes

Remember when your teacher assigned you a hefty chapter to read? You flipped 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.

According to research by Sung and Mayer (2012), 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 figures truly worth a thousand words.

### Write the caption first

Often times, it is 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.

#### Exercise

Target Audience: CS undergraduate students taking an “Introduction to Data Structures” class.

Consider the following three figures, each of which uses the same caption.

Caption A. A single-linked list holds content and a pointer to the next node.

Caption B. A single-linked list holds content and a pointer to the next node.

Caption C. A single-linked list holds content and a pointer to the next node.

Which of the three preceding figures 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 first 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 fine painting, gradually uncovering layers of insight and meaning. People pay good money to do exactly that in the world’s art museums.

Figure 2. You’d happily study this Van Gogh painting.

[Portrait of Pere Tanguy By Vincent van Gogh - Musée Rodin Public domain]

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 five 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 whittling visual clutter into something coherent and helpful is to organize complex systems into subsystems, like those shown in the following figure:

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.

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 ellipse in the following figure, 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 find 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]

### Illustrating is re-illustrating

As with writing, the first 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 text contrast sufficiently with its background?
• What’s the takeaway?

For instance, consider the evolution of the London Tube map. 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.

In 1931, Harry Beck revolutionized a new type of public transit map that simplified 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, 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?

Some possible issues with the diagram include:

• Issue: The bright colors pull the reader’s attention away from other parts of the diagram. Solution: Choose colors carefully so that they do not overpower the diagram.
• Issue: The diagram does not have sufficient 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.
• Issue: The arrows currently point in both directions which makes it unclear which way the diagram flows. 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 also additional issues in the diagram that are not identified here.

Here is an improved illustration:

Figure 11. A simplified version of the preceding diagram.

What flaws do you see in the improved illustration?

Here are two of the flaws 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 benefit 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:

When exporting diagrams from these tools to use in documentation, it is usually best to export the files as SVG or Scalable Vector Graphics. Scalable Vector Graphics easily scale diagrams based on space constraints so that no matter the size, you end up with a high quality image.

## 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 is a different language than code, 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.

Sample code is an opportunity to directly influence 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 difficult 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 deeply nested code.
• Optional: Use bold or colored font to draw the reader’s attention to a specific 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)

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

• 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 sacrifice 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")


The comments contain the following flaws:

• The comment elaborates on a fairly obvious part of the code.
• 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

• 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 inefficient 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 benefit the reader. For example:

Good

# 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 first and most basic example in a sample code set is usually termed a Hello World 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 samples:
1. A function that takes no parameters and doesn’t return anything.
2. A function that takes one parameter but doesn’t return anything.
3. A function that takes one parameter and returns one value.
4. A function that takes three parameters and returns one value.
2. The following set of functions:
1. A function that takes three parameters and returns one value.
3. The following set of functions:
1. A function that takes one parameter and returns one value.
2. A function that takes three parameters and returns one value.

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, please take it.

A quick compilation of the topics covered in Technical Writing Two is available on the Summary page.

## Summary of Technical Writing Two

Technical Writing Two covered the following intermediate lessons of technical writing:

• Read documents out loud (to yourself).
• Find a good peer editor.
• Outline a document. Alternatively, write free form and then organize.
• Introduce a document’s scope and any prerequisites.
• 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 through discontinuities.
• Create concise sample code that is easy to understand.
• Keep code comments short, but prefer clarity over brevity.
• 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, point out dragons.

As time permits, consider reviewing these additional technical writing resources.

### References

[1] Technical Writing One: https://developers.google.com/tech-writing/one?hl=zh-cn [2] Technical Writing Two: https://developers.google.com/tech-writing/two?hl=zh-cn [3] Words: https://developers.google.com/tech-writing/one/words?hl=zh-cn [4] 1: https://developers.google.com/tech-writing/one/active-voice?hl=zh-cn#Footnote1 [5] Words: https://developers.google.com/tech-writing/one/words?hl=zh-cn [6] sesquipedalian: https://www.google.com/search?q=sesquipedalian&hl=zh-cn [7] www.markdowntutorial.com: https://www.markdowntutorial.com/ [8] Mastering Markdown: https://guides.github.com/features/mastering-markdown/ [9] Summary: https://developers.google.com/tech-writing/one/summary?hl=zh-cn [10] technical writing resources: https://developers.google.com/tech-writing/resources?hl=zh-cn [11] Technical Writing One: https://developers.google.com/tech-writing/one?hl=zh-cn [12] self-study units: https://developers.google.com/tech-writing/one?hl=zh-cn [13] Google Developers: https://developers.google.com/?hl=zh-cn [14] Google Developer Documentation Style Guide: https://developers.google.com/style?hl=zh-cn [15] style-guide highlights: https://developers.google.com/style/highlights?hl=zh-cn [16] active voice: https://developers.google.com/tech-writing/one/active-voice?hl=zh-cn [17] numbered lists: https://developers.google.com/tech-writing/one/lists-and-tables?hl=zh-cn [18] Write in the second person: https://developers.google.com/style/person?hl=zh-cn [19] Place conditional clauses before an instruction: https://developers.google.com/style/clause-order?hl=zh-cn [20] code-related text as code font: https://developers.google.com/style/code-in-text?hl=zh-cn [21] Audience: https://developers.google.com/tech-writing/one/audience?hl=zh-cn [22] Style and authorial tone: https://developers.google.com/style/tone?hl=zh-cn [23] Nirmal Dulal [CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0)]: https://commons.wikimedia.org/wiki/File:Nepalese_Children.JPG [24] Sung and Mayer (2012): https://www.sciencedirect.com/science/article/pii/S0747563212000921 [25] 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 [26] NASA / JPL-Caltech / University of Arizona [Public domain]: https://commons.wikimedia.org/wiki/File:Phobos_colour_2008.jpg [27] evolution of the London Tube map: https://wikipedia.org/wiki/Tube_map#History [28] [Public domain]: https://commons.wikimedia.org/wiki/File:Tube_map_1908.jpg [29] modern tube map: https://www.google.com/search?tbm=isch&q=london+tube+map&hl=zh-cn [30] standard color contrast recommendations: https://material.io/design/color/text-legibility.html#legibility-standards [31] Google Drawings: https://drawings.google.com/?hl=zh-cn [32] Draw.IO: https://draw.io/ [33] LucidChart: https://www.lucidchart.com/pages/ [34] Scalable Vector Graphics: https://wikipedia.org/wiki/Scalable_Vector_Graphics [35] Hello World program: https://wikipedia.org/wiki/"Hello,_World!"_program [36] Summary: https://developers.google.com/tech-writing/two/summary?hl=zh-cn [37] technical writing resources: https://developers.google.com/tech-writing/resources?hl=zh-cn