01.01 Planning

⇐ Key concepts ⇐ ⇑ Course overview ⇑ ⇒ Writing ⇒

The writing process

Creating documentation is not simple. People rarely just sit down at a keyboard and type out the perfect document in one sitting. Writing is a process. Take it step by step.

Planning: This is where you make sure you won’t have to task-switch later on. In the same way that you should check that you have all of the ingredients before you start cooking, use the planning stage to get everything ready before you start writing.
Writing: This is the most fragile step in the process. It’s the one you don’t want to interrupt with research, or with worrying about things you can fix later. In fact, splitting the process up into steps is mostly designed to protect this stage and reduce the chance of writer’s block.
Editing: During the writing step, promise yourself that you’ll fix your terrible prose later. Then at editing time, you can actually do those fixes. Editing is done in a series of methodical, achievable steps.

Planning for your audience

The most important thing to think about in writing is your audience. Who will be reading what you write?

You don’t have to think about personas the way advertising copywriters or user experience professionals do. You don’t need to know your readers' names or their favorite colors. But there are things you need to know so you can communicate with them effectively.

Roles and goals

Every character should want something, even if it is only a glass of water.

— Kurt Vonnegut

Think about your audience in terms of their information needs. What they need depends on why they’re reading your document. What will they do with the information you’ll give them?

For technical writing, you generally have audiences with two different professional roles. People in the different roles have different goals, and thus different information needs:

Business users: People who want to use the documentation to make a decision. Buy this software or not? Use this functionality in the product design or not?
Engineers: People who want to use the documentation to make something. An app, a component, a feature.

Readers with different roles also tend to have different backgrounds. Business users, even ones with an engineering background, read differently than engineers do. They make different assumptions and find different things important.

Knowledge

You also need to think about your audience in terms of their knowledge. There are three kinds of knowledge to consider.

What they don’t know

You know your subject. Unfortunately, it can be easy to forget how it feels not to know it. But as a writer, you need to put yourself in the shoes of your audience, to meet them where they are. That includes remembering and respecting their lack of knowledge. (That lack is what makes them your audience, after all.)

What they should know

Also known as assumed knowledge. This is the fundamental knowledge they need to have, or they’re not your audience. For example, the programming language you’re working with.

What you hope they know

Limited, clearly-defined things that are specific to your topic. If they don’t know it, they can look it up fairly easily. Things like:

Domain-specific knowledge
Specialized vocabulary or special meanings of common terms
Standards and conventions

You don’t have to explain these things. Provide good search terms or links to reliable sources and let your readers find them on their own.

Note

Your documentation won’t teach your readers everything. You’ll have to draw the line between what you plan to teach them and what you won’t.

For instance:

Things that are confidential/trade secrets.
Things that are not relevant to their goals.
Hidden details, such as implementation details or the inner workings of algorithms.

Mental models

People can only take in information if they have a framework to organize it. This framework is called a mental model.

Whatever you’re documenting, its existence started with someone thinking about a problem in a particular way. How they thought about that problem — their mental model — determined how they solved it, what abstractions, analogies, design patterns, and approaches they used.

Your reader needs to share that mental model or your documentation won’t make any sense to them.

What does it look like when your reader doesn’t share your mental model?

When my younger brother was about 4 years old, he loved riding in elevators. As a treat, we took him to a building whose elevators had glass walls. We rode one several times. Afterwards, we asked him, "What was special about that elevator?"

We expected him to say something about glass, but what he said was, "It goes up and down."

His mental model of an elevator was something like A box that you go into and press a button. You feel funny for a little while, then the doors open and you’re somewhere different. He didn’t understand how the different places related to each other, or how the elevator connected them.

Imagine explaining that your elevator got stuck between floors to him.

Your audience may be in the same situation with what you’re documenting. Ensure that somewhere early on in the documentation (in a "Key Concepts" section or an introductory paragraph), you give them enough of a mental model to understand everything else you want to teach them.

Planning your document

Image of a woman being embraced by text.

Once you have a better understanding of your audience and their needs, the next thing to plan is how to meet those needs.

Purpose

What is the purpose of your document? Can you state it in one sentence?

What are you explaining?
To whom?
So they can do what?

You don’t have to include it the documentation, but keep it in mind as you work. It’s your North Star, your insurance against scope creep or topic drift.

For instance: This course teaches the basics of technical writing to people in different technical roles so that they can write better.

Scope

You have to choose the scope of your documentation. How much information should you put in there?

The rule is to only include information that supports your reader’s goals. The challenge is to know what that means for your documentation.

You can’t just shrug and put everything in just to be safe. Otherwise your document will be as thick as the New York phone book. This creates two problems:

Your readers will have trouble finding what they need.
You’ve just created a pile of technical debt, because everything you wrote has to be maintained.

But don’t include too little:

If there are gaps in what you’ve written, some of your readers will find themselves without any help.
Your document should be a coherent whole, rather than a collection of links the reader has to piece together.

Trim your document down to what your readers need to know. The precise "cut here" line depends on the document, but don’t skip things like mental models and troubleshooting for when things go wrong.

Vertical scope

One way to avoid writing too much is to understand what documents already exist, and how they relate to what you need to write. There may be a stack of documents on a given system, ranging from a high-level description for business users to very low-level detailed content aimed at developers.

Know what documents are above and below the one you’re working on. For each of them, be aware of:

Their scope, so what you write integrates smoothly with them. You don’t want to leave a gap for your readers to fall into, or duplicate content that you then have to maintain.
The mental models and vocabulary they use. Even if you use different ones, you need to be compatible with them
Where they are, so you can link to them. Think about permissions here: are they available to your audience?

Caution

Each "layer" of the documentation on your subject, including the one you write, should be able to stand on its own. You can refer to another document for extra information but don’t depend on it for necessary information.

Horizontal scope

You need to figure out the scope of the task from your reader’s point of view:

Where does it start?: What are the entry criteria? What is the definition of ready?
Where does it end?: What are the exit criteria? What is the definition of done? How will they know they’re done?

The boundaries of what you do may not be the boundaries of what your audience wants to do.

Horizontal bar with four regions, A & B being what the team does and B & C being what the reader needs to meet their goals. A & B are highlighted.

Horizontal bar with four regions, A & B being what the team does and B & C being what the reader needs to meet their goals. B & C are highlighted.

You may do stuff that your reader doesn’t need to know about it…however cool you find it. Don’t include it.
You do stuff your reader needs to know about to meet their goals. That’s why you’re writing this documentation.
Someone else does stuff your reader needs to meet their goals. You don’t have to write this documentation, but you need to provide access to it. Make sure that the documentation is well-maintained. Give your readers a conceptual bridge to it (for example, a map of parameter names between the two).
Totally irrelevant. Don’t write about this.

This is another way you need to step out of your own context and into your reader’s.

Note	Case C is the one exception to the requirement that documents can stand on their own.

Document structure

Image of the internal metal frame of a building under construction.

Documentation needs good, consistent structure.

A good structure reduces the reader’s cognitive load by introducing the right information at the right times.
A consistent structure teaches the reader how to find everything, then uses that knowledge on throughougt the documentation.

If you’re updating an existing document, make sure you work with the structure that’s already there. Are you adding the information in the right place? Is it at the same level of detail as the other items that are described in the same section? You may need to add information in more than one place, with different levels of detail or different things being emphasized.

If you’re writing a new document:

Is there a known template to use? Do you have the latest version of it?
Is there an example of the kind of document you are trying to write? Can you re-use its structure?

References

Image of reference books in Trinity College Library in Dublin.

Instead of rewriting supplementary content that already exists, link your readers to existing sources. This came up in the context of audience knowledge and document scope, but it’s important whenever you’re referring to things outside of your document.

Before you send readers to another document, you need to do evaluate the source:

Evaluate its reliability. Is it:
- accurate?
- clear?
- well-maintained?
Look at its scope. Make sure that there’s no gap between your scope and the external document’s. If there is, you’ll need to bridge it.
Map its vocabulary. If the external resource uses different terms than you do, tell your readers as you provide the link. That will reduce your readers' cognitive load as they go back and forth.

Word list

Image of Santa Claus reading a long list.

This is something you should make for yourself. You’ll probably add to it as you write and edit your documentation.

The words you use in your writing should have a 1:1 relationship with the ideas they represent. (This will come up later). Your word list is how you keep track of what words you’re using and what exactly they mean.

Decide which words you’re going to use and what they will mean (and how you’re going to capitalize, punctuate, and spell them) and note them down. If your team does this often, consider having a team word list somewhere. Also check the spelling, capitalization, and punctuation with the word list in your organization’s style guide.

Bonus: if your documentation will need a glossary, you’ve started that too!

Exercise

To practice what you’ve just learned, do the planning exercise.

⇐ Key concepts ⇐ ⇑ Course overview ⇑ ⇒ Writing ⇒