?

Log in

Tue, May. 31st, 2005, 10:29 pm
symmys: Are manuals stupid?

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.

Wed, Jun. 1st, 2005 06:08 pm (UTC)
(Anonymous)

Ideally, there should be two help systems: quick help (usually given in tooltip whem mouse hovers over an item) and more detailed one. You are right that most of manuals are too long and detailed. But -- whatever the templates say (btw: I am one of template authors) - it is your manual. Feel free to write somehting like: "File menu contains a number of commands. Most of them are self-explanatory. Here is the explanation of the more complicated ones".

And, of course, the help button, say, in preferences dialog should bring up the section of the manual which explains preferences dialog -- not "About "

However, IMHO, having a manual which contains only FAQ-style (or quick-and-dirty help) is a bad idea. Manual should cover all features of the program -not just answer most common questions. What does a user do if he needs help with some feature which is not so frequently asked? Again: as a compromise, you can have a FAQ section in the manual, and have this be the default page that opens when one clicks "help" button.

Wed, Jun. 1st, 2005 07:05 pm (UTC)
symmys

Thanks for you feedback — I realize I came off a bit harsh in my reflection (and blush a bit realizing the gnome documentation folks are reading!).
Thinking again about a development/writing model, rather than the ideal product — I might propose that a quick-and-dirty, FAQ style help might grow into a full manual over time. And your permission to write "Such and such is self-explanatory... moving on..." may help ease that transition.
Also, FAQs tend to be task-oriented rather than feature/component-oriented by nature ("How do I X?" rather than "What does X do?"). As a result, I think that they may actually evolve into better docs than moving through the program a function at a time would do.
Maybe that's a pipe dream... but since the default behavior for a developer who prefers programming to writing modules (i.e. me) is to write nothing, I figure quick-and-dirty is a step up :)

Thu, Jun. 2nd, 2005 11:48 am (UTC)
(Anonymous)

Manuals also can - and should - be task-oriented, rather than listing all menu commands. I quite agree here.

-------------
Sasha Kirillov

Thu, Jun. 2nd, 2005 12:39 pm (UTC)
atomic0x

You could always have a link to a faq from the help menu, or the manual.

Thu, Jun. 2nd, 2005 09:35 am (UTC)
cuu508

I can hardly remember myself using help system. Long time ago, with no internet-access at home.
These days, If I'm stuck with a problem, I google.
If I want to learn a new app, I find a tutorial for it (sometimes in a form of "Quick Start" section in Help, but not the other, ordinal "Help" sections)
OK, I use MS Office Help occasionally, - when I have a pretty good idea of what I'm looking for, and I know for sure it's in the help - that's reference.

I think, the reason why I avoid help systems, is, that, they are usually incomplete, outdated and inefficiently organized. There's very little possibility I will find the specific stuff in there, the usual stuff I can figure out by myself.

Yes, there are too many I's

Tue, Jun. 28th, 2005 10:27 pm (UTC)
cparker

Wow. This is perfect. My wife has been looking for a program such as this for the last year or so. I was thinking about writing something such as this, but you've saved me the trouble!

I realize that you suggest to donate money to sf.net and/or the FSF... but... you're not accepting donations at all??

Wed, Jun. 29th, 2005 03:39 am (UTC)
symmys

Well, I certainly haven't been expecting donations. A while ago, though, someone offered a "bounty" of sorts (they wanted me to add support for printing on Windows and said they'd donate if the feature showed up) so I went ahead and did the set up at SF to receive donations. They never did donate, though... Long story short, you could donate directly to Gourmet here if you like.