Essentials of Technical Writing

In this lesson, we cover some of the essentials you should keep in mind when planning, writing, and releasing documentation and training content.

Plan a release based on feedback

At the beginning of a release, don’t just figure out what new features will be in the product and plan to doc those—also check with the product team to find out what areas they think need improvement from the last version of the documentation, and check user forums and support queries for the questions people are asking. Start working on improving this content right at the end of a release, before the next release is really underway when your time will be mostly focused on documenting new features.

Work like an investigative journalist

When you’re first learning about a feature, work like an investigative journalist and focus on “getting the story.” Be curious and keep wondering what the user will ask next. Always ask and answer the question “why?”, and use the active voice wherever possible so that it’s absolutely clear who is doing what and when. For example, consider this sentence:

The configuration must be updated to ensure all new users can access the application.

How does the configuration get updated? Does it happen automatically when a user signs up? Does an admin have to do it?

Instead, write this:

When you add new users in the batch file, you must also update the configuration file to give the new users immediate access to the application.

Write for less-technical users

Developers often create products with a certain audience level in mind, and usually they assume the audience is a lot more familiar with the company's technology than they actually are. In reality, users often need more hand-holding and simple instructions than developers might think. As you’re talking to an engineer or reading their spec or initial write-up, keep an image of a less-savvy user in mind and ask the questions that person would ask.

Never assume the user has read the introductory material, as they probably landed on that page by doing a web search. So make sure there are links back to the introductory material, definitions, etc. If someone unfamiliar with the product can understand it, you’ve communicated your message clearly.

Structuring a topic

Start with the concepts they need to know (link off for more info), then how to do it, and then additional reference info. This follows the “inverted pyramid”:

most important -> less important -> least important

The first paragraph should follow this structure:

• Basic overview of the feature
• What problem it solves
• Who needs this feature
• Example (if needed)
• Why this is useful (so what?)
• Very brief overview of “how”

Then go into details after the intro. For example:

The foo feature enables you to remotely delete all data and applications from a user’s device (also called “wiping” the device). This feature ensures that the data on your users’ devices will not be compromised if their device is lost or stolen. 

A foo agent runs in the background on the user’s device and will therefore decrease battery life slightly, so it is most appropriate for users who a) have confidential data on their devices and b) do not need to maximize battery life. 

After you enable foo on your server and install the agent on the user’s device, you can run foo from the Admin dashboard when you need to wipe the device.

To enable foo on the server:
1. (instructions)
2. (instructions) 

To install the foo agent on a device:
1. (instructions)
2. (instructions) 

To remotely wipe a device:
1. (instructions)
2. (instructions)

Likewise, you should name the topic based on what someone is trying to do:

Remotely wiping a device

is more informative than:

Using the foo feature

Refine the content

Warnings, gotchas, and prerequisites should appear before you tell them how to do something, never after. For example, imagine the support calls you'd get if you wrote this:

To delete data:  

1. Navigate to foo > bar.
2. Enter your admin code.
3. Click Delete.
4. When prompted, click Yes to proceed.  

Note: Only click Yes if you want to delete all the data in your system. You should make a backup before you do this.

Instead, you should write something like this:

To delete all your data: 

WARNING! This procedure will permanently delete all the data in your system. 

1. Make a backup of your data.
2. Navigate to foo > bar.
3. Enter your admin code.
4. Click Delete.
5. If you are sure you want to delete all the data in your system, click Yes to proceed. 

For information on restoring the data from your backup, see Restoring Data.

Notice the intro now indicates this will delete all your data, making a backup is part of the procedure so it's harder to miss, and the confirmation step reiterates that this will delete all your data. Additionally, I've added a helpful link after the procedure that tells you how to restore your data in case you went through these steps and realized you didn't actually want to do this.

This approach puts the most important information first (there's that inverted pyramid again), adds cues to help remind the reader what this is going to do, and anticipates a scenario where someone made a mistake. By thinking through what the reader wants to do and may inadvertently do, you can refine the content to be as helpful as possible.

Simplify the language

Cut out all extraneous words. For example:

made arrangements for -> arranged

made the decision -> decided

made the measurement of -> measured
performed the development of -> developed
is working as expected -> works as expected

Break up long sentences and paragraphs. Use bulleted lists instead of listing options in a sentence, and use bold text to highlight the main points. Remember, readers aren’t here to read; they’re here to get the information as quickly as possible.

There's a very nice example of this here.

Keep the reader’s goal in mind

Why are they here, and what do they want to know? For example, look at this sentence:

This law was introduced in 2011, after a long, drawn-out process of appeals, to ensure that agency workers are given some of the same employment rights as their full-time counterparts.

In this example, the end goal is for the reader to find out about employment rights. The information about the legal appeals process is not essential, so remove it:

This law was introduced in 2011 to ensure that agency workers are given some of the same employment rights as their full-time counterparts.

Many developers want to provide as much specific detail as possible, but this can come at the expense of readers understanding the main point. For example:

The system can process multiple requests per second. One customer processed 5,165,345 requests per second. Another customer processed 10,725,335 requests per second.

Instead, write:

The system can handle enormous loads. One customer’s implementation regularly processes over 10 million requests per second, which was twice as much as their previous system could handle.

Remember, people want information, not just data. So give data as needed but always explain what it means. In this case, people want to know if it can handle very large loads, and giving the higher number as an example is sufficient, plus adding some info about why this number is significant (dig in and find out more about the example…in this case, it’s assuming you did your research and discovered that the load was twice the customer’s previous capacity).

Use the inverted pyramid for sentences as well. For example, instead of this:

You can enter the information manually each time, but it’s better to configure it as a property.

Write this:

Configure the information as a property so you don’t have to enter it manually each time.

Use graphics wisely

Use screenshots when needed to orient the user, but don’t include them in every single step, or they can easily get lost. Animated GIFs are especially nice for showing how to navigate somewhere that’s hard to explain in text, but keep in mind that you must also add Alt text to all graphics to describe what’s happening in the image for those who are visually impaired.

Examples are crucial

Have you ever noticed that you may read the first sentence describing a feature and still not really understand what it is, but then the next sentence gives a real-world example that helps you attach the concepts to something tangible? The best way to clarify your content is through examples. Not everything merits an example, while more complex concepts may need more than one example. When you’re documenting properties, giving examples of actual values helps a lot. And when describing how to write code, samples are essential.

Test all the steps

It’s critical that you test and document all the steps in a procedure and not just rely on the steps that were given to you. People who know the technology well will often leave out small but important steps (such as restarting the server after making configuration changes), which results in support queries.

Review your content

Walk away and then come back and re-read your work to catch mistakes. And then always get a second pair of eyes on your writing. No matter how experienced you are, you will always make mistakes you can’t see, so peer reviews are important.

Likewise, whenever possible, get someone new to the technology to test out the procedures you’ve written.

Lastly, get a subject-matter expert to review your content to make sure you didn’t miss anything, and also ask for best practices that users should know. This will take your content from covering the basics to being more deeply insightful and useful to advanced users.

Get feedback from users

Look at the support queries and questions on user forums to see what people are asking and where they’re running into trouble.

Summary

Our ultimate goal is to reduce support queries to zero, so: 

• Ask good questions up front
• Structure the content using the inverted pyramid
• Write simple, accurate, fully tested content that gives information and not just data
• Provide good examples and graphics where needed
• Include best practices that will help users go beyond the basic steps

This approach will help ensure the users are successful and the support people are bored.

Additional resources

https://medium.com/@limedaring/five-tips-for-improving-your-technical-writing-and-documentation-47353723c8a7

http://www.copyblogger.com/technical-writing/

http://www.wikihow.com/Master-Technical-Writing

http://web.mit.edu/me-ugoffice/communication/technical-writing.pdf

http://idratherbewriting.com/2014/06/20/10-technical-writing-principles-to-live-by/

https://tech.co/tips-technical-writing-2015-11

Coordinate vs. Cumulative Adjectives

In the previous lesson, we covered hyphens and dashes. Now, we're ready to move on to a tricky topic: coordinate vs. cumulative adjectives.

Coordinate adjectives individually modify a noun and are separated by a comma. For example, look at “heavy” and “bulky” in the following sentence:

• The heavy, bulky box was awkward to carry. 

You can tell that they're coordinate adjectives because they would still sound correct if you used “and” between them, such as:

• The heavy and bulky box was awkward to carry. 

or if you changed their order:

• The bulky, heavy box was awkward to carry. 

Also, if you have adjectives from the same category, such as two opinion adjectives or two size adjectives, you use a comma. For example:

• The beautiful, elegant box sat on the mantle. 
• The gigantic, enormous box was impossible to lift. 

Note that adjectives from the same category are rare in technical writing, as they’re mostly used to be emphatic. In tech writing, we aim to be precise but concise.

Cumulative adjectives are used when the adjectives are from different categories (e.g., age and size) or when the final adjective before the noun creates a compound noun. This is especially true when you specify origin (nationality/religion). For example, "and" sounds wrong between these adjectives, so you don't use a comma:

• Correct: She was a smart Muslim woman 
• Incorrect: She was a smart and Muslim woman 

But you could say “She was a smart and beautiful woman”, so these would be coordinate adjectives instead of cumulative:

• She was a smart, beautiful woman. 

Here comes the crazy part: cumulative adjectives must be in a specific order based on their category. This order is as follows, with examples for each category:

1. Opinion: good, attractive, delicious 
2. Size: large, small, enormous 
3. Age/Condition: old, new, modern, worn 
4. Length or shape: long, short, square 
5. Color: red, blue, green 
6. Origin (nationality, religion): American, Muslim 
7. Material: plastic, wooden, cotton 
8. Purpose: electric (wire), tennis (shirt) 

For example, these are in the correct order:

• An attractive young American lady 
• A modern Japanese electric car 
• A big square blue box 

But the following examples are NOT in the correct order and sound all wrong:

• An attractive American young lady 
• A Japanese modern electric car 
• A blue square big box 

This is hard to memorize, and it just takes practice. Most native English speakers have no idea that this order even exists; they just do it naturally and know something is wrong when they hear them out of order. I recently told a friend about this order and he laughed at me, refusing to believe this rule exists, until I started rearranging adjectives in a sentence. His eyes got wide, and he quickly changed the subject.

There are sites that show a much longer and more detailed list of categories, but it's simpler to stick with the more concise list above. In fact, if you search for "cumulative adjectives", you'll find a different list on most pages. I've chosen the list that I think covers the most important categories.

Summary

Coordinate adjectives are separated by a comma and sound fine if you change their order or insert "and" between them instead of a comma. Cumulative adjectives are not separated by a comma and must be placed in a specific order based on their category.

In the next lesson, we'll take a break from punctuation and talk about the essentials of technical writing.

Additional resources

http://wilcoxediting.com/articles/2009/04/07/comma-between-adjectives
https://www.khanacademy.org/humanities/grammar/parts-of-speech-the-modifier/adjective-order-and-commas-with-adjectives/v/commas-and-adjectives

Hyphens and Dashes

In the last lesson, we took a deeper look at commas. In this lesson, we will explore the difference between hyphens, en dashes, and em dashes. 

Hyphens

A hyphen connects two words that are closely related and are acting as a single word. For example:

• Two-thirds of survey respondents said they needed additional training.
• This number is toll-free. 

However, in some cases, you only connect the words with a hyphen when they are acting as an adjective modifying the word that follows them:

• This architecture supports high availability when traffic increases. (“availability” is a noun, and “high” is an adjective modifying it)
• To handle traffic spikes, design a high-availability architecture. (“high-availability” is a compound adjective modifying “architecture”)
• Next, you check in your files. (“check” is a verb, “in” is an adverb modifying “check”)
• The server sends a check-in notification. (“check-in” is a compound adjective modifying “notification”)

Words that are hyphenated often end up as open compounds (that is, they have a space instead of hyphen). “Open source” is an example of an open compound:

• This software is open source.
• This open source software is free to use. (No hyphen between "open" and "source")

And eventually, they may even become a single word. For example, "email" evolved like this:

Electronic mail -> e-mail -> email

“Log in” is still two words when it’s a verb:

• You can now log in to the application.

But it’s a single word when it acts as an adjective:

• Your login information was sent to your email address. 

Note: Why wouldn't you say "You can now log into the application"? Aren't you supposed to combine "in" and "to" when they're next to each other? In cases like "Look into this for me", the answer is yes. But in this example, "log in" is a phrasal verb, meaning that the verb "log" and the adverb "in" must go together and act as a single verb. Therefore, if you combined "in" and "to" to make "into", you would be splitting the "log in" phrasal verb in half, and "log" would be sad that "in" ran off with that scoundrel "to".

The Microsoft Manual of Style (and some other style guides) instructs us NOT to use hyphens after “-ly” adverbs:

• These are often-asked questions. 
• These are frequently asked questions. (No hyphen after an "-ly" adverb)

Irritating side note: Some grammar guides say you DO hyphenate after an “-ly” adverb IF the second word in the compound is the past participle. In this case, “frequently-asked questions” would require a hyphen, since “asked” is the past participle of the verb “to ask”, whereas “frequently upsetting incidents” would not use a hyphen, because "upsetting" is the present participle (not the past participle) of the verb "to upset". Confused? Don't be, because we’re going to ignore that stupid rule and stick with the Microsoft Manual of Style!

Dashes

There are two types of dashes: en dashes and em dashes. En dashes are longer than hyphens but shorter than em dashes.

-    hyphen
–   en dash
—  em dash

En dash
En dashes are uncommon. They connect two things that are related to each other by distance, essentially replacing the word “to”. For example:

• Take the San Francisco–New York flight.
• I read this in the May–September issue of the magazine.
• This certificate is valid 2017–2018.

Note: If you want to use "from" in the last example, use "to" instead of the en dash. For example:

• This certificate is valid from 2017 to 2018.

OR

• This certificate is valid 2017–2018.

But NOT:

• This certificate is valid from 2017–2018.

To type an en dash, see: https://www.howtotype.net/symbol/en-dash/

Em dash
The em dash is longer and is more common than the en dash. It sets off and emphasizes additional information in the sentence and can be used in place of commas, a colon, or parentheses—as I just did in this sentence. For example:

• When the car was finally delivered three months after it was ordered, she no longer wanted it.
• When the car was finally delivered, three months after it was ordered, she no longer wanted it.
• When the car was finally delivered—three months after it was ordered—she no longer wanted it. 

The second example uses commas to offset and emphasize the phrase. The third example uses em dashes to emphasize it even more, indicating how irritating it was that it took three months for the car to arrive.

Here's an example of an em dash replacing a colon:

• The white sand, the warm water, the sparkling sun—this is what brought them to Hawaii.

To type an em dash, see: https://www.howtotype.net/symbol/em-dash/

Summary

Hyphens connect two words that are closely related. En dashes connect two things that are related by time and replace the word "to". Em dashes set off a part of the sentence to give it extra emphasis. 

In the next lesson, we will look at coordinate vs. cumulative adjectives.

Additional resources

http://www.thepunctuationguide.com/hyphen-and-dashes.html