Three Types of Documentation You Should Stop Writing

How do you decide what to write about? How do you organize what you’ve written? Often, your view will be shaped by the technology you’re used to. Mallard users will think of topics and guides. DITA users will turn to tasks and concepts. DocBook users will line up chapters and sections. All of these have their pros and cons, but there are three types of documents you need to stop writing.

README: Read you? I’ll read what I like, thankyouverymuch. What’s in this README file? Instructions for how to use the software? How to install it? Develop plugins for it? Start contributing to it? The answer to all of these is yes, and much more. I just don’t know what’s in there. All I know is that somebody thinks I should read it. Maybe.

TODO: I want to know what I can do with your software today, not tomorrow, and certainly not in your imagined tomorrow. By all means, keep a TODO list. Better yet, use an issue tracker. Software development is hard work, and we all need help keeping track of what we need to do. But don’t put it in your user documentation.

FAQ: I don’t care if my question is frequently asked. There are many ways you could organize information, but an FAQ isn’t a taxonomy. It’s a brain dump of answers to some questions somebody had. Worse, it’s often a brain dump of answers to questions the developers think you should ask. (Did anybody really ask how your project got its witty name?) Identify the valuable information in your FAQ and take the time to work it into the organizational structure of your documentation.

All of these are failures to identify the audience and organize information for them. A writer’s job doesn’t end with writing some words and just putting them somewhere. When writing and organizing, always think of where your reader is likely to look for the information you’re providing.

Become a Better Writer: Explain More

The essence of technical writing is explaining. Whether you’re writing an introductory tutorial or a massive reference manual, your goal is always to explain something to the reader. It follows that to be a better writer, you should be a better explainer. And as with any skill, you get better with practice.

Take opportunities to explain things to people. Remember that guy at the gas station asking for directions? Take a few minutes out of your day to help him. Think about his frame of reference. Will he be able to recognize local landmarks? Does he know which way North is? Think about the different ways he could accomplish his task. The route you would take isn’t necessarily the best route to send him on.

Explaining things to people will help you understand how others might think. You get used to the things you know, and it’s sometimes hard to articulate everything to somebody else. You might leave out steps that seem obvious to you. The more you explain things, the better you will become at anticipating gaps in your explanations.

If a colleague asks you to explain your work or your decisions, do it. Don’t treat it like a challenge or a distraction. Explaining will help you better understand the subject: the best way to learn is to teach. And it will help you create things that make sense to other people.

Try taking things a step further and writing instructions for things in life. Sure, it could be about complicated technology, like programming your VCR. But you can write instructions for low-tech things too. If you like to cook, write instructions for one of your favorite meals. Then ask somebody else to cook from your instructions. Remember that terms that are familiar to you might be lost on your reader. Does your reader know the difference between simmer and sauté?

By explaining things through instructions, you practice explaining without immediate feedback. Face-to-face instruction is wonderful, but it’s not a luxury you have when writing documentation. You have to take your skills in explaining things and put them to use in an environment where you can’t see confused facial expressions or answer questions.

Make a habit of explaining better in everyday life, and you will find you’re more able to create things that other people actually understand.

Creative Commons Attribution 3.0 United States
This work by Shaun McCance is licensed under a Creative Commons Attribution 3.0 United States.