On Fri, 8 Sep 2000, Jeremy Wadsack wrote:
>
>
> "Bob Puff@NLE" wrote:
>
> > The biggest thing the online docs need are examples, and defaults.
>
>
> Such as a (well written) HOWTO? Man pages are generally designed to work as
>references. The Analog docs are designed to be a guide (with reference ability
>through the
> index and report references). Perhaps a series of good HOWTOs would be helpful to
>the Analog community.
I am 100% in agreement with this, and it's very near the top of my "todo"
list. Perhaps the list could suggest topics for HOWTOs? Virtual hosts is
obviously one, but I'm a bit short of others.
As for defaults, I don't really want to document them in the main
documentation, which is already rather long. They can all be gleaned from
examples/big.cfg and from anlghea2.h in the source. But the best way is "try
it and see" and change it if you want something different from the default.
> As a developer who also writes his own documentation, I will say what all
> developers say: No matter how good or bad I may be at documentation,
> writing user docs is not as fun as writing code. So it becomes last
> priority. <off-topic> The open-source community could be helped greatly by
> technical writers (there are people out there who think writing users docs
> is fun, right?) donated some of their time to the projects.</off-topic>
>
>
> > 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. 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.
--
Stephen Turner http://www.statslab.cam.ac.uk/~sret1/
Statistical Laboratory, Wilberforce Road, Cambridge, CB3 0WB, England
"The new operating system will recover more easily from system crashes."
(Microsoft, aiming high with Windows Millennium)
------------------------------------------------------------------------
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]/
------------------------------------------------------------------------
