For eight years, I made most of my income from technical writing. Not the relatively glamorous technical writing involved with writing articles about free and open source software (FOSS) – glamorous, that is, to those who haven’t done it (those of us who have done it are usually considerably less starry-eyed) — but basic how-tos and detailed instructions to accompany hardware and software. Looking back, I must have been reasonably good at the job, since I went from a beginner to a consultant with a sub-contractor in eight months, and kept myself steadily employed most of the time and well-employed much of the time.
Based on that experience, I would like to offer some advice for those who are trying to fill the gaps in FOSS documentation. It’s a thankless job, under-appreciated and laborious, but, if you’re going to attempt it despite all the disincentives, you might as well do it properly. After all, your satisfaction in doing the job properly might easily be your only reward:
- You must become an expert in what you are writing about: Some professional technical writers pride themselves on being specialists in communication, and feel they don’t need to know the details of what they are writing about. You can always tell manuals done by them, because they are shallow and have large gaps in them. Likewise, you can always tell this type of technical writer, because they’re despised by any developer with whom they work. The truth is that, while you don’t need to be an expert when you start documenting, if you aren’t expert by the time you’re finished, you aren’t doing the job properly.
- It all comes down to structure: Anybody with average intelligence or better can learn to write a coherent sentence or paragraph. However, structuring several hundred pages is hard work – much harder work than the actual writing. The need to structure is also why you need to become an expert in your subject; if you’re not, how can you know what information to put first, or what’s missing? Don’t be surprised if you spend 50-75% of your time in planning the structure, or if your first outline changes drastically as you work. Both are indications that your work is developing the way that it should.
- In the majority of cases, the best structure will be a list of tasks, arranged from the most basic or earliest to the most complex or latest: It will almost never be a list of menu items and taskbar icons, except in brief introductions to the interface. This task-orientation is a major reason why you need to be an expert in what you are writing – if you’re not, you won’t have any idea of what users might want to accomplish.
- Think of your audience as being attention-deficit: Knowing your material is necessary, but it can also make you forget what new users need to hear. The best way to write to the level you need is to project yourself imaginatively into the position of a new user, but, if you can’t manage that, imagine that you are writing for people with low attention spans who are easily bored. The result may spell out the obvious for some readers, but other readers will be glad that you are thorough. Always remember: What is obvious to you isn’t obvious to your readers.
- Don’t worry about style: In fiction, writers often call attention to their style. By contrast, non-fiction like technical writing is not about you. Your job is to provide simple, clear prose in which you are invisible. And if that sounds boring or unchallenging, you might consider Isaac Asimov’s observation that stain glass windows have been made for over a millennium, while clear glass was a much later development. In many ways, writing simply and clearly is much harder than writing with flourishes and personality. Focus on clarity and content, and let other style considerations take care of themselves. You’ll be surprised how well they work out without you thinking consciously about them.
- Use structured prose whenever possible:Bullet lists, numbered lists, tables, and callouts on diagrams – all these techniques are conciser and easier to understand than straight prose
- Your first draft is probably going to be terrible: But that doesn’t matter, so long as it improves by the end. What matters in the first draft is getting something that you or others can analyze for gaps and make estimates about the finished documentation from. Probably, the physical act of writing will be no more than 25% of your time. Often, it will be much less. If you’re planned properly, and begin writing with a thorough understanding, it should almost feel like an afterthought.
- Don’t mix writing and editing: Writing is a creative process, editing a critical one. If you try to mix the two, you will probably do both poorly. You may also find yourself freezing up and being unable to write because your self-criticism is interfering with your ability to write.
- Make sure editing is part of your schedule: Editing should not be a last-minuted effort. Instead, accept it as an important part of your schedule. Expect it to fill 10-20% of your time.
- Editing is about structure as well as words: Editing is not just about spelling or correcting grammar. It’s just as much about the structure of the work.
- Get second and third opinions: When you have just finished writing, you are probably unable to judge your work effectively. Get other people to review your work in as much detail as possible. If you can’t get other people to review, put the manuscript aside for several days. If you can’t put it aside, print it out, or take a break before returning to it.
- Expect revisions: Based on my experience teaching first year composition at university, I can say that the average person takes 3 to 4 drafts to produce their best work. You may be naturally talented or reduce that number with practice, but don’t count on either until you have some experience.Make sure you budget the time. You’ll know if your efforts are succeeding if the general trend is that each draft becomes quicker and quicker to write. If that doesn’t happen – especially if you have to keep reinventing the structure or making major additions – then something is probably seriously wrong.
With any given piece of writing, you may not be able to follow each of these pieces of advice. Deadlines in particular may keep you from giving each of these points the attention it needs. But keep all these points in mind, and you will be more likely to write documentation that people actually use, instead of an after-thought to the software that is never used.
Off the Wall 