---

Released 3 May 1998
Minor changes 30 November 1998 

---

We accept Mastercard/Eurocard/Maestro/JBC and Visa!

---

Tip of the month is edited by Peter Ring, PRC (Peter Ring Consultants, Denmark)
- consultants on how to write user friendly manuals

---

Thanks to Adam Sharp <adam@afs.net.au> for inspiration to this month's tip.

If you have corrections, better texts or suggestions for improvements, please let me know.

If there is more than one technical writer on a document

The technical writers' product information sources

• Written material, mainly:
• R&D reports, incl. technicians'/programmers' draft manuals.
• Product definition documents.
• Online-help written by technicians.
• Software source code with comments - that's why it is often a good idea if the technical writer has at least some knowledge to programming, preferably to the programming language used.
• "Interviewing" the technicians/programmers who has designed the product + the product manager in charge of the product. "Interviewing" is here put in "" because it is better to regard it as a "pupil controlled teaching" action rather than an interview (more about that later).
• Working with the product itself, either the real product or a PC based dummy.

Your learning process mirrors the users learning process

A special problem is, that you most often will have to start writing the manual before the product development has been completed. In fact, you should start writing it as a "user interface product specification" before they start developing the product - but that's another story.

Initial information collection

1. Start getting someone demonstrating the product for you. Ask a lot of questions about ...
• who the users are. For complex products, who are the users for the basic functions, the more advanced users, the super-users, etc. For each level, what can you expect them to know/handle. What about their reading capabilities? The User Map (see Tip of the month January 1996 ) is a very useful tool here.
• where this product is used.
• which other products it looks like.
• typical applications.
• what are the fundamental idea(s) behind this product and its applications.


Be aware, that very often nobody as a complete oversight over the product it's use and applications. Very often the very first person to get this oversight is YOU.

2. Define the structure for manual or the manual system.
1. Write the chapter headings as far as you can and define them as headings at their proper level (heading1, heading 2, etc.). Use a checklist to make sure you've got them all.
2. Define which kind of users each chapter/section is to be written for.
3. Don't be afraid of needing to change it later on. Today, moving a chapter is a question of minutes if the documentation has been written properly making all references automatic links, - or e.g. "see $$$" where you can then search for $$$ later on.

Write the manual

3. Write the chapters/sections/elements which are (fairly) stable: Front-page, headers/footers, introduction, standard disclaimers, the automatically generated list of contents, etc. Because you wrote the headings, the generated list of contents is a good first "shopping list" for the information needed.
4. Try to install the product (if applicable) and use the product's basic functions. Make a list of the problems you meet. Start writing ...
• the basic application explanations. These will be useful for yourself defining in details which instructions you will have to write, their content, and who to write them for. Add the new chapter/sections names to the document on their proper places.
• instructions for the basic procedures. You will probably at the beginning be finding yourself swapping back and forward between basic applications and basic procedures, making mistakes both places. Don't worry - regarding the product you are still a pupil, and a pupil is permitted making mistakes to be corrected by the teacher. That is the classical teaching process.
5. Interview the specialists. Or rather: Let the specialists teach you how to use the product:
• Only let him/her press the buttons for an introductory explanation. Let the teacher explain what to do, but insist on doing it yourself. That's the only way to learn. It may look like a slower process because s/he can do it so much faster, but in the long run it pays because YOU learn a lot more from making the mistakes while the teacher is looking at you, able and ready to guide you, rather than watching a glossy presentation you can't follow anyway. Let him/her understand s/he has a teachers role.
• Don't try to learn too much per lesson, max. approx. 1 hour lessons. Start with the parts of the product which is "stable", that means where the design is in principle completed (knowing very well, this is no guarantee against last minute changes).
6. Then go back and try to write the chapter related to the lesson you just had. As far as possible collect your questions to technician/programmer and ask them in bundles rather than disturbing them over and over again.

Test the manual

7. Let the technicians read the chapters you have written about their special part of the design. Where you have made errors,
• correct them.
• be aware, that a point where you made a mistake is very likely a critical point, where "real" users may do the same mistakes. Improve your (procedure) descriptions as needed.
• If a procedure is very complicated or user un-friendly try to suggest improvements in the (graphical) user interface. Users and user interface is most likely an area where YOU are more expert than the technician/programmer. If you know about programming, and what's possible or not, difficult or easy, it is a lot easier for you to be heard here.


Do NOT follow their ideas about how things should have been written, unless you personally agree. This is YOUR expertise and YOUR responsibility towards the final users.

8. Make a round to the designers asking for info about changes made since last. Correct/add/delete as needed.
9. When a first draft is completed, distribute it to a wider range of suitable experts and listen to their comments, following the same guidelines as above.
10. When completed make a suitable number of usability tests, using test persons with a background comparable with the background of the final typical weaker end users. Wherever somebody runs into problems, other people will do the same. Correct and test again, until the problems are solved.

Get it out!

11. Get it printed - and listen very carefully to the field experiences about problems with the documentation. Correct and re-issue as needed.

Ideas for new "Tip of the month" subjects are VERY welcome, too!

Go to last month's tip .
Go to a list of old tips .
Return to the User Friendly Manuals' homepage . 

.

.

.