Since a lot of our documentation will be largely rewritten for ProjectMallard, we could think about the tone and style of the user manuals.
This page is just some rough ideas for now. Please comment and add your own.
General style
Generally, our docs are quite stuffy, formal, and at times downright robotic. This makes them hard to read and depressing to write. I've been looking at OS X docs lately. Maybe we could learn from them and relax a little.
Application names and the APPLICATION tag -- we tend to write "Use the Calculator Application...". Compare with "You can use Calculator to..." in OS X's help, or "To learn more about what you can do using Preview...". There's no convoluted "the Beanstalk Application", or even italics. It's just assumed the user knows and recognizes the applications name, even with "Calculator" and "Preview" that are common vocabulary words.
- To introduce a series of instructions, we tend to say "Perform the following steps". OS X help just presents a numbered list in a coloured frame. It's assumed the user knows what this means. PArt of this is that the list usually occurs in a topic that's about a specific procedure, e.g. "Planting beans". When it's less obvious, the list is introduced: "To plant some beans:". But again, it's assumed that the user can see what follows are steps to be followed.
Interface vs Task-based help
Most of our documentation is interface-based: the help basically walks you through the interface, telling you what each thing does. A section on a dialog box, for example, lists each control and tells you what it does.
This is great if you want to *completely* understand the application. But most users don't want a guided tour. They are thinking 'I want to do X and I want to do it now. Tell me how!'
Providing answers to this sort of question requires task-based help: topics that have titles like 'Installing a printer'. For this to work, help needs to be easily searchable, as when task topics pile up it gets harder to organize them logically.
Task-based help needs to be backed up with interface help. (Personal anecdote: MS Word help went task-based about 10 years ago. I often find myself wanting to know what a specific dialog box option does. I can't find that in the help!)
Task-based help still needs to explain parts of the interface and what it does. Here's an example of task-based help gone too far:
- 8.3.1.2.11. To save your current network configuration as a "Location" Press the Add button besides the Locations menu, specify the location name in the window that pops up.
The user might say: what's a 'location'? What does it do? Why might I want one?
References
There is some great Free Software documentation out there. Most of the longest-lived tools (emacs, vim, perl, awk, etc.) have great documentation. Read the Gnus manual, and you'll be laughing out loud! I think part of this is that the manual writer feels more comfortable because he is addressing his peers (people who know how to program). When writing documentation, try not to talk down to the reader. Loosen up.
There's probably a lot to learn from other manuals. If anyone else has ideas, please add them.