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.
