I would like to echo the opinion that of freeware (and much commercial
ware) analog is among the best, easiest to make immediate use of, most
richly and usefully documented packages around.
nice work!
-Dave Dennis
Seattle, WA
On Mon, 18 Sep 2000, Jeremy Wadsack wrote:
> Date: Mon, 18 Sep 2000 09:52:35 -0700
> From: Jeremy Wadsack <[EMAIL PROTECTED]>
> Reply-To: [EMAIL PROTECTED]
> To: [EMAIL PROTECTED]
> Subject: Re: [analog-help] Newbie help - Apache woes?
>
>
>
> 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]/
> ------------------------------------------------------------------------
>
------------------------------------------------------------------------
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]/
------------------------------------------------------------------------
