Stephen Turner wrote:
> On Fri, 8 Sep 2000, Jeremy Wadsack wrote:
> >
> > "Bob Puff@NLE" wrote:
> > > That being said, the docs are pretty good, just very technical.
> >
> > I disagree (sorry, no offense Stephen, but I suppose that's why you're a
> > post-doc in statistics not technical writing). I think the organization of
> > the docs is hard to understand. On the other hand, I view the world in a
> > different way that you, Chris or Bob, (or Stephen or anyone else). That's
> > why well documented products allow you to learn in different ways. And
> > well designed products don't require documentation (but still provide it
> > all). At least that's the goal. Most consumer products are like this (your
> > toaster came with a manual, but you never had to read it). Most consumer
> > products are exceedingly less complicated as well.
> >
>
> Actually, unlike many free software authors, I do take the documentation
> seriously, and work hard on it.
Sorry, I'm not denying that you've put a lot of work into it. I can see that. And it's
always up to date, which is more than can be said for much of the free software out
there. (Anyone ever looked at the documentation for PHP? Arrgh!)
> But I have a very wide audience, from people
> who want ten pictures of the buttons to press for each task, to sysadmins
> with ten years of experience. It's very difficult to write docs to satisfy
> both. In fact I get about as many comments that the documentation was
> unusually easy to follow as complaints that it was unreadable. Not that I
> don't continue to strive to improve them.
Here's my take on this: Sysadmins (either by necessity or by selection) are good at
learning from references. Most other people learn well from tutorials and guides. Many
people like examples to learn from. Some people still learn well by "playing" (most of
us had this drilled out of us in grammar school :).
Ideally documentation should be provided in all these methods. A comprehensive
reference to all commands, arguments, etc. (that can be printed out, including
defaults). A
quick-start tutorial that walks a new user, step by step, through the process of
getting the first report. A series of HOWTOs to provide topical guides for specific,
common
tasks (virtual hosts, scheduling and rotating, etc.). A collection of applicable and
interesting examples. Descriptive messages and output to help users know what their
changes are doing.
Analog provides most of this (in fact, I can think of a certain other software package
that could benefit from much of this :). I think that there's still (and always will
be) room for improvement. Here are some examples from my own experience (this might
not be representative of other users, so perhaps it's not worht listing, but just in
case...):
It took me several months to discover that there was a complete list of all commands
in the index. The "Quick Reference" was added after I was already familiar with most of
the commands. I never read "Analog's definitions." Rather I learned from responses of
helpful users on this list. For some reason, it never ocurred to me to read the
documentation "front-to-back". I always skipped around and read different pages, never
used the "next" link on each page.
Anyway, I hope that's of some use.
Jeremy Wadsack
Wadsack-Allen Digital Group
------------------------------------------------------------------------
This is the analog-help mailing list. To unsubscribe from this
mailing list, send mail to [EMAIL PROTECTED]
with "unsubscribe" in the main BODY OF THE MESSAGE.
List archived at http://www.mail-archive.com/[email protected]/
------------------------------------------------------------------------
