A while ago I tried to start writing a manual for my GNOME-based app, Gourmet, but never finished.
This weekend, I was doing some sophisticated usability studies (e.g. making my parents try my program), when my father suggested there should be some “help” to explain the way Gourmet’s shopping list worked. It occurred to me that of course there should be, and that this was actually quite a trivial thing to write documentation for, but that I hadn’t gotten to it because I’d been following the GNOME documentation project’s templates and tried to write a basic manual, moving through everything my app could do.
The thing that I realized then, was that this was foolish. If it was tedious for me to write, it would be tedious for the vast majority of users to read. More importantly — the important information would get lost in the thicket of generic instructions.
To the extent that my application is like other good applications, no manual is necessary. Want a new recipe? Click on “New recipe” in the “File” menu.
What users need, is something quick and dirty for the occasional non-obvious feature (non-obvious features don’th ave to be bad features — they’re actually some of my favorites, they just take a second to explain).
The idea of having a confused user look to the “Help” menu and bring up a link to clunky old Yelp with a template-style manual rather repels me — and that’s the real reason I haven’t written the docs. Helpful help would probably look a lot more like a short FAQ — short enough that useful information can be gathered in a minute or two, easily searchable, and only bothering to answer questions people actually ask.
I don’t mean to imply the gnome documentation project is completely off base — obviously they’ve done a lot of thinking and work on their templates. But I do wonder if there might not be a better model for writing application documentation — something that would not only be easier for developers to sit down and write, but also more helpful to the average user.