Improving Your Technical Writing

11:55 Outline/Mindmap first.

It doesn’t matter which of these approaches you use, but you need to organize your thoughts before putting them on paper. You want a rough idea of what is going to be around a piece of text before writing it. If you are linking within the document, having these sections set up as anchors makes them easy to link to, even if they aren’t filled in with content yet.

Make sure that your outline makes sense before you start writing. There should be a logical flow when reading from one end of the document to the other. People should also be able to scan the table of contents of your document (or the outline in word) and get to the stuff they want to read.

17:25 Use your reader’s vocabulary.

Don’t make up terms for things when people already have a term for it. Resist the temptation to be pedantic unless it’s actually required for the purpose of explanation. Remember that people are reading your technical documentation to learn something or to make a decision. They aren’t referencing it for college papers.

Try to write for the reader’s level of education and experience. You will alienate your reader and they will tune you out if you use big words too often. A technical document is an explanation of something for a particular group. That particular group is not “everybody”.

18:55 Include graphics

Graphics give people something to examine as a supplement to your writing. This can help avoid small misunderstandings becoming big ones. Graphics also help people that can’t visualize what you are saying to understand you. Graphics can also be reused in other contexts for different audiences with less editing than text requires.

Graphics can also make things clear that are difficult to express in text. They are a good way to get out of difficult writing situations. If it gets too difficult to explain something verbally, often a graphic can make the explanation easier. You’ll also find that if you can’t explain something well and a create a graphic, that the explanation becomes easier afterward (it’s like outlining in that it forces organization of thoughts).

21:15 Format your text

It should be easy to navigate through the content of your document, either by scrolling or by using a table of contents. Most people scan rather than reading and you need to accomodate that. Use proper heading levels (H1 in HTML, Heading 1 in word) start new sections. This lets automated tools figure out the document outline without your help.

Break things down into reasonably small sections (a page or two at most). Remember, the goal is to make it so that someone can answer a question quickly. Subheadings are good to use to make it easier for people to know where they are when scanning.

24:25 Lay things out based on tasks for the user, not groupings for the developer.

Don’t ever build documentation that shows things screen by screen, table by table, etc. for non-developers. Documentation for end users that is laid out in the way the developer thinks about things is not good for the end user. If the user needs to know which screen to use to do something, having things indexed by screen is not helpful.

Show how to accomplish tasks (or how tasks would be accomplished). If you do things in a task-based manner, people can get an answer to their question and get back to their work. Make your headings task oriented as well, so that people scanning can find their answers quickly.

26:15 Avoid making it personal in tone.

The extra words are unnecessary. Instead of saying “next, you want to click the ‘OK’ button”, just say “Click the ‘OK’ button”. The extra content is more than just wasted text, as it may confuse some readers, especially if English isn’t their first language. It also wastes the time of people using text to speech.

Also avoid directly mentioning individual’s names in documentation. Instead of saying, “send an email to Bill, the CFO”, say “send an email to the CFO”. That way, when the CFO changes you don’t have to change your documents. If you mention departments instead of roles (“Accounting” instead of “CFO”), you also insulate yourself from a lot of policy changes as well.

29:50 Be explicit with text on UI elements

When describing how to do something using a user interface, be very clear about which element you are referring to. Instead of “click the button”, say “click the ‘Save’ button”. This makes it easy to update your documentation when someone changes the text of the UI element, because you can find documents referring to it by the text.

This also makes it less likely that someone will misinterpret your directions. The misinterpretation is less likely when you tell them exactly which element to use. This is especially true over time as the interface may shift around a bit before you can catch up on the documentation.

31:35 Consider accompanying documentation with a cheatsheet where appropriate.

If you are building documentation for end users, it’s useful to include some very short reference materials targeted for specific people. This is much less intimidating than a manual and thus more likely to be used. It’s also handy if something is small enough to be printed out and laminated on a user’s desk.

Cheatsheets are also really helpful for onboarding new users by giving them just enough to get started. This lets the new user focus on the most critical items first. Cheatsheets can also be targeted for specific job roles, while the manual probably covers several.

33:25 Let it mellow between writing and editing

You won’t see grammar and logic errors in your writing if it is fresh in memory. You’ll tend to see what you meant, not what you read. You’ll also come up with better ways for content to flow after you’ve stepped away from it for a while.

If you can’t wait, then someone other than you needs to edit. This is similar to the phenomenon where developers can’t effectively test their own code. Documentation, specifications, and the like are also first-class project outputs and require a similar level of care to code.

36:45 Consider user personas in your writing

You need some demographic information on the different “types” of consumers of your written documentation. This can be everything from a rough idea of their employment and social background, to their education level. Basically, you want to make sure that your documentation is targeted towards the people who are likely to read it. This lets you read back over content to make sure that it will be understood in the way that you intend by your readers.

If your organization doesn’t currently use user personas, you may need to make them up on your own. This doesn’t have to be formal, but you want to avoid the situation where you use vocabulary that is too complex for people that can’t handle it, or too simple for those who can. The idea is that they can read it as if it were written by someone at or near their own level, and avoid having an emotional reaction to it.

39:20 Make time-sensitive references obvious

When expressing why something is done a certain way, make sure to reference those reasons if they might go away or changed. For instance, if you are building an email application, instead of saying “due to spam prevention laws”, you should say “due to section X of the CAN-SPAM act”. Any time you say “at the present time”, you should probably put the current year in parenthesis, just so someone doesn’t assume the document is newer than it is.

If regulatory constraints are critically important to a document, list the regulatory constraints on the document somewhere easily accessible within the document. When you have to go back and fix a bunch of documentation, because some new law came out a year ago and you forgot, you’ll be able to actually find the documents that matter. This can also allow an astute reader to ask smarter questions in new circumstances. For instance, if your document only covers US laws and your company has a branch in Denmark, people reading your documents may realize that these aren’t intended for them.

42:40 Read out loud after writing

Watch out for homonyms and near-homonyms in close proximity. They/Their/There and She saw / See saw close together in text kinda sounds weird. These put focus on the writing rather than the content.

Watch out for subjunctive (If I were you) as it is confusing to non-English-as-first-language speakers. Using overly complex grammatical structures is usually not a good idea if the concept can be expressed more simply. This structure tends to sound wrong even when used correctly, so it’s distracting.

This will also catch a lot of grammar errors, or awkward wordings that may need to be touched up. We get this automatically when recording our podcasts as we trip over wording by each other – it has changed our writing. Remember that a lot of people hear the words in their head as they are reading. You don’t want that voice to get tongue-tied.

46:50 Use internal references

Within your documents, you should also give the user an easy way to “jump” from the current section to one that is referenced. This is why headers and the like are so helpful. It makes it easier to add these as you get close to finishing documentation. HTML anchor tags are also good for this sort of thing.

If the document is of any length, you should also include a table of contents. When a reader is using an electronic form of your document, they can quickly navigate. When combined with proper headings and sections, this will also reduce the amount of effort you spend keeping the table of contents up to date.