Well to me, I am a system administrator in Openface, ISP in Montreal. Honestly, I've
didnot set up webstats before on Unix but I did it on NT. Regarding analog, well I
read most of the documentations just to know the program and how it works. I cannot
add to Bob about his point but sure I can say that documenataion is pretty good. It
may need some other additions and most of the times syadmins learn some stuff from
mailing-lists which I agree with Jeremy.
Wisam
Jeremy Wadsack [[EMAIL PROTECTED]] wrote:
>
>
> 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]/
------------------------------------------------------------------------
