| Part of Speech | Definition | Example |
|---|---|---|
| Noun | A person, place, concept, or thing | Sam runs races. |
| Pronoun | A noun that replaces another noun (or larger structure) | Sam runs races. He likes to compete. |
| Adjective | A word or phrase that 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 represent people, places, or things.
Proper Nouns - Specific names of people, places, or organizations.
Common Nouns - General names for things.
Concrete Nouns - Names of things that can be experienced through the senses.
Abstract Nouns - Names of ideas, qualities, or states that cannot be seen or touched.
Collective Nouns - Words that represent a group of people, animals, or things.
Gender-specific Nouns - Some nouns have different forms for different genders.
Pronouns are an indirection layer—pointers to or substitutions for other nouns or sentences.
Personal Pronouns - Refer to specific persons or things; subject forms & object forms
Possessive Pronouns - Indicate ownership.
Reflexive Pronouns - Refer back to the subject of the sentence.
Demonstrative Pronouns - Point to specific things.
Relative Pronouns - Introduce relative clauses, connecting clauses to a noun or pronoun.
Interrogative Pronouns - Used in questions.
Indefinite Pronouns - Refer to nonspecific things or people.
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. Some sentences contain multiple verbs.
Adjectives modify nouns. Most adverbs modify verbs. Adverbs are not necessarily right next to their verb. Adverbs can also modify adjectives or other adverbs.
Prepositions specify the relationship between two things. Some prepositions answer the question, "Where is this thing relative to that other thing?".
print function falls within the main routine.Other prepositions answer the question, "When is this event relative to that other event?".
Conjunctions connect phrases or nouns within a sentence; transitions connect sentences themselves.
The most important conjunctions are as follows:
For example, in the following sentence, and connects "code" with "documentation," while but connects the first half of the sentence with the second.
The most important transitions in technical writing are as follows:
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 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.
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.
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.
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.
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:
Many pronouns point to a previously introduced noun. Such pronouns are analogous to pointers in programming. Like pointers in programming, pronouns tend to introduce errors. Using pronouns improperly causes the cognitive equivalent of a null pointer error in your readers’ heads. In many cases, you should simply avoid the pronoun and just reuse the noun. However, the utility of a pronoun sometimes outweighs its risk (as in this sentence).
Consider the following pronoun guidelines:
It & They
The following pronouns cause the most confusion in technical documentation:
Python is interpreted, while C++ is compiled. It has an almost cult-like following.
Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in their core may cause accidental mass unfriending.
This & That
Consider two additional problem pronouns:
Running the process configures permissions and generates a user ID. This lets users authenticate to the app.
To help readers, avoid using this or that in ways where it's not clear what they refer to. Use either of the following tactics to clarify ambiguous uses of this and that:
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.
Passive voice examples
By contrast, here's that same sentence in passive voice:
The mat was sat on by the cat.
Some passive voice sentences omit an actor. For example:
The mat was sat on.
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:
A past participle verb is typically a plain verb plus the suffix ed. For example, the following are past participle verbs:
Unfortunately, some past participle verbs are irregular; that is, the past participle form doesn't end with the suffix ed. For example:
Putting the form of be and the past participle together yields passive verbs, such as the following:
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:
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:
Frombus variable to False.Sentences that start with an imperative verb are typically in active voice, even though they don't explicitly mention an actor. Instead, sentences that start with an imperative verb imply an actor. The implied actor is you.
Many sentences contain multiple verbs, some of which are active and some of which are passive.
Use the active voice most of the time. Use the passive voice sparingly. Active voice provides the following advantages:
Be bold—be active.
Passive voice runs rampant through certain scientific research reports. In those research reports, experimenters and their equipment often disappear, leading to passive sentences that start off as follows:
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.
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:
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:
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_trickthat 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_trickstores the current accuracy.The
met_trickvariable stores the current accuracy.
You can sometimes repair a There is or There are sentence by moving the true subject and true verb from the end of the sentence to the beginning. For example, notice that the pronoun you appears towards the end of the following sentence:
There are two disturbing facts about Perl you should know.
Replacing There are with You strengthens the sentence:
You should know two disturbing facts about Perl.
In other situations, writers start sentences with There is or There are to avoid the hassle of creating true subjects or verbs. If no subject exists, consider creating one. For example, the following There is sentence does not identify the receiving entity:
There is no guarantee that the updates will be received in sequential order.
Replacing "There is" with a meaningful subject (such as clients) creates a clearer experience for the reader:
Clients might not receive the updates in sequential order.
Adjectives and adverbs perform amazingly well in fiction and poetry. Thanks to adjectives, plain old grass becomes prodigal and verdant, while lifeless hair transforms into something lustrous and exuberant.
Adverbs push horses to run madly and freely and dogs to bark loudly and ferociously. Unfortunately, adjectives and adverbs sometimes make technical readers bark loudly and ferociously. That's because adjectives and adverbs tend to be too loosely defined and subjective for technical readers. Worse, adjectives and adverbs can make technical documentation sound dangerously like marketing material.
For example, consider the following passage from a technical document:
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.
Software engineers generally try to minimize the number of lines of code in an implementation for the following reasons:
In fact, the same rules apply to technical writing:
Finding the shortest documentation implementation takes time but is ultimately worthwhile. Short sentences communicate more powerfully than long sentences, and short sentences are usually easier to understand than long sentences.
Focus each sentence on a single idea, thought, or concept. Just as statements in a program execute a single task, sentences should execute a single idea.
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.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 extra words and feel enormous happiness in removing or reducing them.
A clause is an independent logical fragment of a sentence, which contains an actor and an action. Every sentence contains the following:
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:
Some subordinate clauses begin with a comma and some don't.
When editing, scrutinize subordinate clauses. Keep the one sentence = one idea, single-responsibility principle in mind. Do the subordinate clauses in a sentence extend the single idea or do they branch off into a separate idea? If the latter, consider dividing the offending subordinate clause(s) into separate sentences.
That and which both introduce subordinate clauses. What's the difference between them? Well, in some countries, the two words are pretty much interchangeable. Inevitably though, alert readers from the United States will angrily announce that you confused the two words again.
In the United States, reserve which for nonessential subordinate clauses, and use that for an essential subordinate clause that the sentence can't live without.
Place a comma before which; do not place a comma before that.
Good lists can transform technical chaos into something orderly. Technical readers generally love lists. Therefore, when writing, seek opportunities to convert prose into lists.
The following types of lists dominate technical writing:
Use a bulleted list for unordered items; use a numbered list for ordered items. In other words:
An embedded list (sometimes called a run-in list) contains items stuffed within a sentence.
Generally speaking, embedded lists are a poor way to present technical information. Try to transform embedded lists into either bulleted lists or numbered lists.
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:
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).
By contrast, the following list is painfully nonparallel along all four parameters:
The following list is parallel because all the items are complete sentences with complete sentence capitalization and punctuation:
The first item in a list establishes a pattern that readers expect to see repeated in subsequent items.
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:
The following numbered list is nonparallel because two of the sentences start with an imperative verb, but the third item does not:
Though different style guides offer conflicting advice about punctuating list items, the Google developer documentation style guide recommends (with some exceptions) starting each list item with a capital letter. For example:
If a list item is a sentence, use appropriate sentence-ending punctuation. For example:
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:
We recommend introducing each list and table with a sentence that tells readers what the list or table represents. In other words, give the list or table context. Terminate the introductory sentence with a colon rather than a period.
Although not a requirement, we recommend putting the word following into the introductory sentence.
The opening sentence is the most important sentence of any paragraph. Busy readers focus on opening sentences and sometimes skip over subsequent sentences. Therefore, focus your writing energy on opening sentences.
Good opening sentences establish the paragraph's central point.
A paragraph should represent an independent unit of logic. Restrict each paragraph to the current topic. Don't describe what will happen in a future topic or what happened in a past topic. When revising, ruthlessly delete (or move to another paragraph) any sentence that doesn't directly relate to the current topic.
Long paragraphs are visually intimidating. Very long paragraphs form a dreaded "wall of text" that readers ignore. Readers generally welcome paragraphs containing three to five sentences, but will avoid paragraphs containing more than about seven sentences. When revising, consider dividing very long paragraphs into two separate paragraphs.
Conversely, don't make paragraphs too short. If your document contains plenty of one-sentence paragraphs, your organization is faulty. Seek ways to combine those one-sentence paragraphs into cohesive multi-sentence paragraphs or possibly into lists.
Good paragraphs answer the following three questions:
The course designers believe that you are probably comfortable with mathematics. Therefore, this unit begins with an equation:
good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills
In other words, make sure your document provides the information that your audience needs but doesn't already have. Therefore, this unit explains how to do the following:
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:
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 role generally share certain base skills and knowledge. For example:
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.
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.
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.
Writing to meet your audience's needs requires unselfish empathy. You must create explanations that satisfy your audience's curiosity rather than your own. How do you step out of yourself in order to fit documentation to the audience? Unfortunately, we can offer no easy answers. We can, however, offer a few parameters to focus on.
Match your vocabulary to your audience. See Words for help.
Be mindful of proximity. The people on your team probably understand your team's abbreviations, but do people on other teams understand those same abbreviations? As your target audience widens, assume that you must explain more.
Similarly, experienced people on your software team probably understand the implementation details and data structures of your team's project, but nearly everyone else (including new members of your team) does not. Unless you are writing specifically for other experienced members of your team, you typically must explain more than you expect.
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.
English has become the dominant language for technical communication worldwide. However, a significant percentage of technical readers are more comfortable in languages other than English. Therefore, prefer simple words over complex words; avoid obsolete or overly-complex English words. Sesquipedalian and rare words repel some readers.
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:
Cake? Bob? Most readers from the United States 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 done.
Idioms are so deeply ingrained in our speech that the special nonliteral meaning of idioms becomes invisible to us. That is, idioms are another form of the curse of knowledge.
Note that some people in your audience use translation software to read your documentation. Translation software tends to struggle more with cultural references and idioms than with plain, simple English.
A good document begins by defining its scope. For example:
This document describes the design of Project Frambus.
A better document additionally defines its non-scope—the topics not covered that the target audience might reasonably expect your document to cover. For example:
This document does not describe the design for the related technology, Project Froobus.
Scope and non-scope statements benefit not only the reader but also the writer (you). While writing, if the contents of your document veer away from the scope statement (or venture into the non-scope statement), then you must either refocus your document or modify your scope statement. When reviewing your first draft, delete any sections that don't help satisfy the scope statement.
A good document explicitly specifies its audience. For example:
This document is aimed at the following audiences:
- software engineers
- program managers
Beyond the audience's role, a good audience declaration might also specify any prerequisite knowledge or experience. For example:
This document assumes that you understand matrix multiplication and the fundamentals of backpropagation.
In some cases, the audience declaration should also specify prerequisite reading or coursework. For example:
You must read "Project Froobus: A New Hope" prior to reading this document.
Engineers and scientists are busy people who won't necessarily read all 76 pages of your design document. Imagine that your peers might only read the first paragraph of your document. Therefore, ensure that the start of your document answers your readers' essential questions.
Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, the start of any long document is the hardest page to write. Be prepared to revise page one many times.
In your career, no matter how creative you are, you will author precious few documents containing truly revolutionary ideas. Most of your work will be evolutionary, building on existing technologies and concepts. Therefore, compare and contrast your ideas with concepts that your audience already understands.
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.
Answering the following questions helps you determine what your document should contain:
For example, suppose you have invented a new sorting algorithm, which is similar to quicksort. The following list contains some potential answers to the preceding questions:
After defining the audience's needs, organize the document to help readers get the information they need. For example, based on the answers in the previous section, the outline for the document could look as follows:
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
--perfflag.If the program runs slowly, then try the
--perfflag.
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.
A period separates distinct thoughts; a semicolon unites highly related thoughts.
Before using a semicolon, ask yourself whether the sentence would still make sense if you flipped the thoughts to opposite sides of the semicolon.
The thoughts preceding and following the semicolon must each be grammatically complete sentences.
You should almost always use commas, not semicolons, to separate items in an embedded list.
Many sentences place a transition word or phrase immediately after the semicolon.
Em dashes are compelling punctuation marks, rich with punctuation possibilities. An em dash represents a longer pause—a bigger break—than a comma. For the musically fluent, think of a comma as a quarter note rest and an em dash as a half-note rest.
Consider the horizontal punctuation marks shown in the following table:
| Name | Mark | Relative width |
|---|---|---|
| em dash | — | widest (usually, the length of the letter m) |
| en dash | – | medium (usually, the length of the letter n) |
| hyphen | - | narrowest |
Some style guides recommend the en dash for certain uses. The Google Style Guide, however, offers the following blunt advice about en dashes:
Don't use.
Hyphens are tricky. Within technical writing, hyphens connect words in certain compound terms, such as:
Confusingly, three-word compound terms often contain a hyphen between the first and second word but not between the second and third word. For example:
When in doubt about hyphens, consult a dictionary, glossary, or style guide.
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.
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:
These are the elements outlined in John Gruber’s original design document. All Markdown applications support these elements.
| Element | Markdown Syntax |
|---|---|
| Heading | # H1 ## H2 ### H3 |
| Bold | **bold text** |
| Italic | *italicized text* |
| Blockquote | > blockquote |
| Ordered List | 1. First item 2. Second item 3. Third item |
| Unordered List | - First item - Second item - Third item |
| Code | `code` |
| Horizontal Rule | --- |
| Link | [title](https://www.example.com) |
| Image |  |
These elements extend the basic syntax by adding additional features. Not all Markdown applications support these elements.
| Element | Markdown Syntax |
|---|---|
| Table | \| Syntax \| Description \| \| ----------- \| ----------- \| \| Header \| Title \| \| Paragraph \| Text \| |
| Fenced Code Block | ``` { "firstName": "John", "lastName": "Smith", "age": 25 } ``` |
| Footnote | Here's a sentence with a footnote. [^1] [^1]: This is the footnote. |
| Heading ID | ### My Great Heading {#custom-id} |
| Definition List | term : definition |
| Strikethrough | ~~The world is flat.~~ |
| Task List | - [x] Write the press release - [ ] Update the website - [ ] Contact the media |
| Emoji (see also Copying and Pasting Emoji) | That is so funny! :joy: |
| Highlight | I need to highlight these ==very important words==. |
| Subscript | H~2~O |
| Superscript | X^2^ |
Underlined text is not something you typically see in web writing, probably because underlined text is nearly synonymous with links. However, if you’re writing a paper or a report, you may need the ability to underline words and phrases. A couple of applications like Bear and Simplenote provide support for underlining text, but Markdown doesn’t natively support underlining. If your Markdown processor supports HTML, you can use the <ins> HTML tag to underline text in your document.
Some of these words <ins>will be underlined</ins>.
The rendered output looks like this:
Some of these words will be underlined.
Tabs and whitespace have a special meaning in Markdown. You can use trailing whitespace to create line breaks, and you can use tabs to create code blocks. But what if you need to indent a paragraph the old-fashioned way, using the tab key? Markdown doesn’t provide an easy way of doing that.
Your best bet might be to use a Markdown editor that supports indentation. This is common in applications that are more oriented towards desktop publishing. For example, iA Writer allows you to customize indentation settings for the editor in the application preferences. It also provides template customization options so that you can make the rendered document look the way you expect it to, indentation and all.
Another option, if your Markdown processor supports HTML, is to use the HTML entity for non-breaking space ( ). This should probably be your option of last resort as it can get awkward. Basically, every in your Markdown source will be replaced with a space in the rendered output. So if you stick four instances of before a paragraph, the paragraph will look like it’s indented four spaces.
This is the first sentence of my indented paragraph.
The rendered output looks like this:
This is the first sentence of my indented paragraph.
Having the ability to center text is a necessity when writing a paper or a report. Unfortunately, Markdown doesn’t have any concept of text alignment (one possible exception is when using tables). The good news is that there’s an HTML tag you can use: <center>. If your Markdown processor supports HTML, you can place these tags around whatever text you want to center align.
<center>This text is centered.</center>
The <center> HTML tag is technically supported but officially deprecated, which means it works for now but you’re not supposed to be using it. Unfortunately, there’s not another pure HTML alternative. You could try using one of the CSS alternatives. Not all Markdown applications provide CSS support, but if the one you’re using does, here’s an alternative to the <center> tag:
<p style="text-align:center">Center this text</p>
Markdown doesn’t allow you to change the color of text, but if your Markdown processor supports HTML, you can use the <font> HTML tag. The color attribute allows you to specify the font color using a color’s name or the hexadecimal #RRGGBB code.
<font color="red">This text is red!</font>
The <font> HTML tag is technically supported but officially deprecated, which means it works for now but you’re not supposed to be using it. Unfortunately, there’s not another pure HTML alternative. You could try using one of the CSS alternatives. Not all Markdown applications provide CSS support, but if the one you’re using does, here’s an alternative to the <font> tag:
<p style="color:blue">Make this text blue.</p>
Some people need the ability to write sentences in their Markdown files that will not appear in the rendered output. These comments are essentially hidden text. The text is viewable by the author of the document, but it’s not printed on the webpage or PDF. Markdown doesn’t natively support comments, but several enterprising individuals have devised a solution.
To add a comment, place text inside brackets followed by a colon, a space, and a pound sign (e.g., [comment]: #). You should put blank lines before and after a comment.
Here's a paragraph that will be visible.
[This is a comment that will be hidden.]: #
And here's another paragraph that's visible.
Admonitions are frequently used in documentation to call attention to warnings, notes, and tips. Markdown doesn’t provide special syntax for admonitions, and most Markdown applications don’t provide support for admonitions (one exception is MkDocs).
However, if you need to add admonitions, you might be able to use blockquotes with emoji and emphasis to create something that looks similar to the admonitions you see on other websites.
> :warning: **Warning:** Do not push the big red button.
> :memo: **Note:** Sunrises are beautiful.
> :bulb: **Tip:** Remember to appreciate the little things in life.
The rendered output looks like this:
⚠️ Warning: Do not push the big red button.
📝 Note: Sunrises are beautiful.
💡 Tip: Remember to appreciate the little things in life.
The Markdown syntax for images doesn’t allow you to specify the width and height of images. If you need to resize an image and your Markdown processor supports HTML, you can use the img HTML tag with the width and height attributes to set the dimensions of an image in pixels.
<img src="image.png" width="200" height="100">
The rendered output will contain the image resized to the dimensions you specified.
Markdown doesn’t natively support image captions, but there are two possible workarounds. If your Markdown application supports HTML, you can use the figure and figcaption HTML tags to add a caption for your image.
<figure>
<img src="/assets/images/albuquerque.jpg"
alt="Albuquerque, New Mexico">
<figcaption>A single track trail outside of Albuquerque, New Mexico.</figcaption>
</figure>
Some people like creating links that open in new tabs or windows. The Markdown syntax for links doesn’t allow you to specify the target attribute, but if your Markdown processor supports HTML, you can use HTML to create these links.
<a href="https://www.markdownguide.org" target="_blank">Learn Markdown!</a>
Markdown doesn’t provide special syntax for symbols. However, in most cases, you can copy and paste whatever symbol you want to use into your Markdown document. For example, if you need to display Pi (π), just find the symbol on a webpage and copy and paste it into your document. The symbol should appear as expected in the rendered output.
Alternatively, if your Markdown application supports HTML, you can use the HTML entity for whatever symbol you want to use. For example, if you want to display the copyright sign (©), you can copy and paste the HTML entity for copyright (©) into your Markdown document.
Here’s a partial list of HTML entities for symbols:
©®™€←↑→↓°πFor a complete list of available HTML entities, refer to Wikipedia’s page on HTML entities.
Markdown tables are notoriously finicky. You can’t use many Markdown syntax elements to format the text in table cells. But there are workarounds for at least two common table issues: Line breaks and lists.
You can separate paragraphs within a table cell by using one or more <br> HTML tags.
| Syntax | Description |
| ----------- | ----------- |
| Header | Title |
| Paragraph | First paragraph. <br><br> Second paragraph. |
You can add a list within a table cell by using HTML tags.
| Syntax | Description |
| ----------- | ----------- |
| Header | Title |
| List | Here's a list! <ul><li>Item one.</li><li>Item two.</li></ul> |
Some Markdown applications like Markdeep can automatically generate a table of contents (also referred to as a toc) from your headings, but this isn’t a feature provided by all Markdown applications. However, if your Markdown application supports heading IDs, you can create a table of contents for your Markdown file using a list and some links.
#### Table of Contents
- [Underline](#underline)
- [Indent](#indent)
- [Center](#center)
- [Color](#color)
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.
Companies, organizations, and large open source projects frequently either adopt an existing style guide for their documentation or write their own. Many of the documentation projects on the Google Developers site follow the Google Developer Documentation Style Guide. 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 the style-guide highlights.
Some of the guidelines listed in the highlights are covered in Technical Writing One. You might recall some of the following techniques:
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:
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 if your writing is conversational, read it out loud. Listen for awkward phrasing, too-long sentences, or anything else that doesn't feel natural. Alternatively, consider using a screen reader to voice the content for you.
For more information on adjusting the style of your writing to suit your audience, see Style and authorial tone.
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.
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.
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.
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:
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:
So, should you organize your material into a single document or into a set of documents in a website? Consider the following guidelines:
The remainder of this unit covers techniques that can be useful for writing longer documents, such as tutorials and some conceptual guides.
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.
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:
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:
Remember that you want to keep your documentation easy to maintain, so don't try to cover everything in the introduction.
Providing navigation and signposting for your readers ensures they can find what they are looking for and the information they need to get unstuck.
Clear navigation includes:
The tips in the following sections can help you plan the headings in your documentation.
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:
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.
Most readers appreciate at least a brief introduction under each heading to provide some context.
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:
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.
It is often helpful to write the caption before creating the illustration. Then, create the illustration that best represents the caption. This process helps you to check that the illustration matches the goal.
Good captions have the following characteristics:
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.
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.
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:
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 Scalable Vector Graphics (SVG). The SVG format easily scales diagrams based on space constraints so that no matter the size, you end up with a high quality image.
Good sample code is often the best documentation. Even if your paragraphs and lists are as clear as blue water, programmers still prefer good sample code. After all, text and code are different languages, and it is code that the reader ultimately cares about. Trying to describe code with text is like trying to explain an Italian poem in English.
Good samples are correct and concise code that your readers can quickly understand and easily reuse with minimal side effects.
Sample code should meet the following criteria:
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.
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:
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.
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.
Follow these recommendations to create clear sample code:
Consider the following recommendations about comments in sample code:
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.
For your reader to easily reuse your sample code, provide the following:
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.
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.
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.
Failure is inevitable; failing to report failures is inexcusable. Failing silently causes the following problems:
Embrace your software's fallibility. Assume that humans will make mistakes using your software. Try to minimize ways for people to misuse your software, but assume that you can't completely eliminate misuse. Therefore, plan error messages as you design software.
Follow the guidelines on error handling in Google's programming language guides, including:
Implement the full error model described in the Errors page of the Google AIP. For instance, note the following quote about implementing error messages in services:
Services must return a google.rpc.Status message when an API error occurs, and must use the canonical error codes defined in google.rpc.Code.
The Errors page of the Google Cloud API design guide provides helpful information about implementing the full error model for Google APIs.
API implementations should not swallow the root cause of issues occurring in the back end. For example, many different situations can cause a "Server error" problem, including:
"Server error" is too general an error message to help users understand and fix the problem. If the server logs contain identification information about the in-session user and operation, we recommend providing additional context on the particular failure case.
Numeric error codes help customer support monitor and diagnose errors. Consequently, specifying numeric error codes along with textual error messages is often quite valuable.
You can specify error codes for both internal and external errors. For internal errors, provide a proper error code for easy lookup/debugging by internal support personnel and engineers.
Document all error codes.
Raise errors as early as useful. Holding on to errors and then raising them later increases debugging costs dramatically.
Tell users exactly what went wrong. Be specific—vague error messages frustrate users.
If the error involves values that the user can enter or modify (for example, text, settings, command-line parameters), then the error message should identify the offending value(s).
If the invalid input is a very long value that spans many lines, consider doing one of the following:
Help users understand requirements and constraints. Be specific. Don't assume that users know the limitations of your system.
Create actionable error messages. That is, after explaining the cause of the problem, explain how to fix the problem.
Supplement explanations with examples that illustrate how to correct the problem.
Not recommended
Invalid email address.
Recommended
The specified email address (robin) is missing an @ sign and a domain name. For example: robin@example.com.
Not recommended
Invalid input.
Recommended
Enter the pathname of a Windows executable file. An executable file ordinarily ends with the .exe suffix. For example: C:\Program Files\Custom Utilities\StringFinder.exe
Not recommended
Do not declare types in the initialization list.
Recommended
Do not declare types in the initialization list. Use calls instead, such as 'BankAccount(owner, IdNum, openDate)' rather than 'BankAccount(string owner, string IdNum, Date openDate)'
Not recommended
Syntax error on token "||", "if" expected.
Recommended
Syntax error in the "if" condition.
The condition is missing an outer pair of parentheses. Add a pair of bounding opening and closing parentheses to the condition. For example:
if (a > 10) || (b == 0) # Incorrect
if ((a > 10) || (b == 0)) # Correct
Write concise error messages. Emphasize what's important. Cut unnecessary text. See the Short sentences unit of Tech Writing One for tips on reducing sentence length.
Not recommended
Unable to establish connection to the SQL database. [Explanation of how to fix the issue.]
Recommended
Can't connect to the SQL database. [Explanation of how to fix the issue.]
A double negative is a sentence or phrase that contains two negative words, such as:
Readers find double negatives hard to parse. ("Wait, do two negatives make a positive or is the author of the error message using two negatives to emphasize something I shouldn't do?")
Not recommended
You cannot not invoke this flag.
Recommended
You must invoke this flag.
Other double negatives are more subtle.
Tailor the error message to the target audience. That is:
Beware of the curse of knowledge when writing error messages. A term familiar to you might not be familiar to your target audience. For example, the following error message contains terminology appropriate for a target audience of ML experts. If the target audience includes a significant number of people who aren't ML experts, then the error message is mystifying:
Recommended for ML experts only
Exploding gradient problem. To fix this problem, consider gradient clipping.
Now compare the following two error messages. The first error message contains technical truth, but terms like server, client, farm, and CPU are not going to help most consumers:
Inappropriate for shoppers
A server dropped your client's request because the server farm is running at 92% CPU capacity. Retry in five minutes.
The second error message is more suitable (and comforting) for a non-technical audience:
Appropriate for shoppers
So many people are shopping right now that our system can't complete your purchase. Don't worry--we won't lose your shopping cart. Please retry your purchase in five minutes.
Use terminology consistently for all error messages within a single product area. If you call something a "datastore" in one error message, then call the same thing a "datastore" in all the other error messages.
Not recommended
Can't connect to cluster at 127.0.0.1:56. Check whether minikube is running.
Recommended
Can't connect to minikube at 127.0.0.1:56. Check whether minikube is running.
Error messages must appear consistently with similar formats and non-contradictory content; that is, the same problem must generate the same error message. For example, if different parts of an app each detect problems with internet connection, both parts should emit the same error message.
A few simple techniques help error messages stand out from the surrounding text and code.
When an error requires a lengthy explanation (for example, multiple sentences) and appropriate documentation is available, use links to redirect users to more detailed documentation.
Not recommended
Post contains unsafe information.
Recommended
Post contains unsafe information. Learn more about safety at .
Some error messages are long, requiring a lot of text to explain the problem and solution. Unfortunately, users sometimes ignore long error messages, intimidated by the "wall of text." A good compromise is to display a briefer version of the error message and then give users the option to click something to get the full context.
For coding errors, place error messages as close as possible to the place where the error occurred.
A surprising percentage of readers are color blind, so be careful with colors in error messages.
Many forms of color blindness exist, so just avoiding a red/green combination isn't sufficient. Because you can't depend on all your users being comfortable with color, we recommend pairing color with another visual cue.
The tone of your error messages can have a significant effect on how your users interpret them.
Instead of telling the user what they did wrong, tell the user how to get it right.
Not recommended
You didn't enter a name.
Recommended
Enter a name.
While maintaining positivity, avoid the words "sorry" or "please." Focus instead on clearly describing the problem and solution.
Not recommended
We're sorry, a server error occurred and we're temporarily unable to load your spreadsheet. We apologize for the inconvenience. Please wait a while and try again.
Recommended
Google Docs is temporarily unable to open your spreadsheet. In the meantime, try right-clicking the spreadsheet in the doc list to download it.
Don't attempt to make error messages humorous. Humor in error messages can fail for the following reasons:
If possible, focus the error message on what went wrong rather than assigning blame.
If an error code exists, include it as part of the error message. Error codes help technical users identify the error and find more information from an error index or error catalog.
Not recommended
Error: You already own this bucket. Select another name from the dropdown list.
Recommended
Error 409: You already own this bucket. Select another name from the dropdown list.
Engineers parse logs to learn how and why errors occurred; therefore, include an Error Identifier to help engineers find particular errors more easily. The Error Identifier should stay constant, even if the textual error message changes.
For more information, see the Errors unit of AIP-193.
Not recommended
{ "error" : "Bad Request - Request is missing a required parameter: -collection_name. Update parameter and resubmit.
Recommended
{ "error" : "Bad Request - Request is missing a required parameter: -collection_name. Update parameter and resubmit. Issue Reference Number BR0x0071" }