Technical Writing Course One - Summary

Words 

 

(1) Define new or unfamiliar terms
• If the term already exists, link to a good existing explanation. 
• If your document is introducing the term, define the term. If your document is introducing many terms, collect the 

definitions into a glossary.

 

(2) 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.
e.g. Telekinetic Tactile Network (TTN)

 

*Don't define acronyms that would only be used a few times.

(3) Disambiguate Pronouns
• Only use a pronoun after you've introduced the noun; never use the pronoun before you've introduced the noun.
• Place the pronoun as close as possible to the referring noun. In general, if more than five words separate your noun from your pronoun, consider repeating the noun instead of using the pronoun.
• If you introduce a second noun between your noun and your pronoun, reuse your noun instead of using a pronoun.

Active Voice - How to make your sentences beautifully clear?

The vast majority of sentences in technical writing should be in active voice. 
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.

 

Clear Sentences 

(1) 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

[Practice] 
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...

Practice - Picking more specific verbs
1. When a variable declaration doesn't have a datatype, a compiler error happens.

->When a variable declaration doesn't specify a datatype, the compiler generates an error message.
2. Compiler errors occur when you leave off a semicolon at the end of a statement.
->If you declare a variable but don't specify a datatype, the compiler generates an error message.

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

(2) Reduce there is/there are
Sentences that start with There is or There are marry a generic noun to a generic verb. 
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.

If no subject exists, consider creating one. 
There is no guarantee that the updates will be received in sequential order.
-> Clients might not receive the updates in sequential order.

(3) Minimize certain adjectives and adverbs

Short Sententces

Why?
• 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.

 

(1) Focus each sentence on a single idea

 

(2) Convert some long sentences to lists

Option A can be converted to B. 

 

A.

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)

B.

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.

(3) Eliminate or reduce extraneous words
The following table suggests replacements for a few common bloated phrases:

 

*Refactoring consists of improving the internal structure of an existing program's source code, while preserving its external behavior. The noun “refactoring” refers to one particular behavior-preserving transformation, such as “Extract Method” or “Introduce Parameter.”

(4) Reduce subordinate clauses (optional) 
When editing, scrutinize subordinate clauses. Keep the one sentence = one idea formula in mind. 

 

(5) Distinguish that from which
 

Lists and Tables 

(1) Choose the correct type of list 
Use a bulleted list for unordered items; 

use a numbered list for ordered items. In other words:
Generally speaking, embedded lists are a poor way to present technical information. 
Try to transform embedded lists into either bulleted lists or numbered lists.

(2) Keep list items parallel

(3) Start numbered list items with imperative verbs

(4) Punctuate items appropriately 
If the list item is a sentence, use sentence capitalization and punctuation. Otherwise, do not use sentence capitalization and punctuation. 

(5) Introduce each list and table with a sentence that tells readers what the list or table represents.
Ex. The following list identifies key performance parameters:

Paragraphs

 

(1) Write a great opening sentence
(2) Focus each paragraph on a single topic
Readers generally welcome paragraphs containing three to five sentences
but will avoid paragraphs containing more than about seven sentences. 
(3) Answer what, why, and how
Good paragraphs answer the following three questions:
-What are you trying to tell your reader?
-Why is it important for the reader to know this?
-How should the reader use this knowledge? Alternatively, how should the reader know your point to be true?

Audience 

-Define your audience
- Begin by identifying your audience's role
- Imagine what knowledge the target audience would have 
- Determine what your audience needs to learn
Write down a list of everything your target audience needs to learn to accomplish goals. 
-Fit documentation to your audience
Vocabulary and concepts. you typically must explain more than you expect.

Coherent Documents

 

(1) State your document's scope
A good document begins by defining its scope. For example:
This document describes the overall design of Project Frambus.

(2) State your audience
a good audience declaration might also specify any prerequisite knowledge or experience.
In some cases, the audience declaration must also specify prerequisite documents.

(3) Establish your key points up front
 Imagine that your peers might only read the first paragraph of page one. 
 ensure that the start of your document answers your readers' essential questions.

Always write a summary for long engineering documents. Although the summary must be very short, expect to spend a lot of time writing it. 

(4) Write for your audience
Answering the following questions helps you determine what your document should contain:
-Who is your target audience?
-What do your readers already know before they read your document?
-What should your readers know or be able to do after they read your document?

Punctuation 

You should almost always use commas, not semicolons, to separate items in an embedded list.

(1) Semicolons
A period separates distinct thoughts; a semicolon unites highly related thoughts. 

(2) Parentheses
-Use parentheses to hold minor points and digressions. 
-Parentheses inform readers that the enclosed text isn't critical.  
-keep parentheses to a minimum in technical writing.

*Standard rules 
If a pair of parentheses holds an entire sentence, the period goes inside the closing parenthesis.
If a pair of parentheses ends a sentence but does not hold the entire sentence, the period goes just outside the closing parenthesis.

 

For example:

(Incidentally, Protocol Buffers make great birthday gifts.)

Binary mode relies on the more compact native form (described later in this document).