What if you can't afford a technical author?

Are you a small business, start-up company (Internet or otherwise), shareware developer or similar? Do you need documentation but didn't think you could have it done professionally? Please contact us.

OK, OK, you can't afford to employ someone to write your documentation for you. You have to do it yourself. That doesn't mean that your documentation has to be as bad as the "documentation" that comes with so much shareware and even commercial software.

Remember that good user manuals and help files are not a "necessary evil". They add value to your product. If you can help your customers save time in mastering your software and become more efficient in using it, you are gaining an advantage over your less enlightened rivals.

Here are a few tips of the trade that may help you to do better. My intention is to raise awareness of the importance of good documentation and to help improve the general standard. This advice is offered free of charge, so you will understand that I am not making any guarantees for it at all. However, I hope you will find it helpful. I don't claim that this is anything like comprehensive. If you want to learn more about technical writing, there are courses on the Web (mostly aimed at students).

Someone wanting the truth is out there...

Before you ever start typing anything (or even putting quill to parchment) you should ask yourself: Who is intended to read this? What situation will they be in when they read it?

In all probability there will be more than one kind of reader, in more than one kind of situation. For example, the system administrator may have to install your software for multiple users on a network or multiple PCs. The end user may use your software to produce a file of some kind, e.g., a document or spreadsheet. The help desk will need to be aware of potential problems for users.

Users don't need or want to read the same things. In fact, they will be quite irritated if they have to read things that are irrelevant to their own needs in order to find what they do need. So, from the start, organise your documentation so that different people need to read only what they need to know. Tell them up front which bits they need to read for different purposes.

General principles:

• Establish who your readers are before you start writing.
• Organise the information so that readers know which bits to read.

Features? Bah! Humbug!

Software developers are obsessed with "features". (A cynic observed that a feature is a bug that has been documented.) Most users care little about them. The few that do are men who spend Sunday afternoon putting go-faster stripes on their cars. Users usually have other concerns, like impressing the boss or getting tomorrow's 9 a.m. presentation ready in time to catch the last train home. They are invariably short of time. They couldn't care less that the new version of your software has a new database engine (what the hell is that anyway?). So here's another general principle:

• User documentation should tell users what your software can help them achieve, and then tell them how to achieve it.

In general:

• Organise manuals and on-line Help according to the tasks that users need to do, rather than features (e.g., menu options or tool bar buttons).

Take it step by step

When you have decided what your software will actually do for the users, then tell them how to do it. General principle:

• Break down each main task into procedures, and each procedure into steps.

1. A heading that describes what the procedure is to do (e.g., "Opening a document" or "To open a document")
2. Further explanation of the procedure, prerequisites and other essential information
3. A numbered, step-by-step set of instructions for carrying out the procedure, in the correct order (of course)
4. Any further comments on the procedure that are not essential for carrying it out

Watch your language

Tools are important, are they not? When you are writing a manual, language is your tool. Choose the right tool for the job:

• Pay attention to the normal rules of spelling, syntax and grammar. Carelessness is irritating to the reader and slows reading down.
• Don't assume things that the user may not have heard of, for example, programming concepts.
• Avoid jargon where it is inappropriate. If an unfamiliar word must be used, provide an explanation in the text, and also in a glossary.
• Address the reader directly, in the imperative mood or active voice and in the present tense. For example, "Enter the date", not "The date is entered"; "The total appears in...", not "The total is seen in..." or "The total will appear in...". (This is not an absolute rule: ignore it if the result sounds awkward and unnatural. If you think it sounds too curt, add the occasional "Please".)
• Keep sentences and paragraphs short. If your sentence has more than two punctuation marks in the middle, consider rewriting it as two sentences to make the meaning clearer.
• Be sparing in the use of "filler" words like "furthermore", "therefore", "thus", "in addition", "actually" and so on.
• When you are listing a number of points of roughly equal importance, often your meaning will be clearer if you use bullets. (Yes, I know Shakespeare didn't use them, but he didn't write manuals.)
• Include humour, certainly, but only if it is appropriate for your audience. Don't distort the document to labour a joke.
• Remember that US humour, slang and examples may not be intelligible in other countries, and vice versa.

S**t!

I know you write only software that is bug-free and fault tolerant, so this section is written for someone else.

There is nothing more fully guaranteed to get people to buy someone else's product than error messages that don't tell the victim what went wrong, and how to avoid the error next time. Ideally, this information should be on the screen. However, if it isn't, it should be in the documentation. General principles:

• Every known error that the user might encounter should be listed in a trouble-shooting appendix.
• Errors should tell the user not only what went wrong, but how to put it right (if possible) and avoid it in the future.

I once bought a program that repeatedly produced a message to the user that read, "Sub or function not defined". This is, professionally, on much the same level as a surgeon leaving the scalpel inside the patient.

Return to top