On Thu, 7 Aug 2003, Don Simons wrote:
> verbosity. Which version is better is a matter of personal opinion: short
> and concise, or leisurely, illustrated, but much longer. I hope the
> re-translation comes out soon so people can see the result and make their
> own choice.
>
> --Don Simons
>
I think that usually multiple entrance levels are required
if the application is sufficiently complex. With the
PMX documentation, most of the time I use the handy reference sheet that
just summarises the commands. but when those commands don't produce
the results i want then it's back to the manual, and failing
that it's off to the mailing list ! SOmetimes I find that
the mere act of writing to the mailing list causes the answer
to constitute itself in my mind :-/
The full range of documentation for end-user applications
can include a wide-range of documents
Installation Guide
User manual (how it works)
Reference Manual (what every function/command does in details but with no
context)
Cook Book (recipes on how to do things)
Quick Start (for beginners having read nothing else just to get some output)
Reference Sheet (for familiar users)
FAQ
Personally, I think FAQs indicate a failing of the documentation
structure. It's a bit like having 'Miscellaneous' in your
filing cabinet... (yes I have a 'Miscellaneous' folder in my
filing cabinet !). I think Cookbooks are a better way to illustarte
how to do certain things, emphasizing the simple and more
obscure features and other FAQ things should find their
way into the more structured documents. But as DOn says,
its a personal thing, how you like your information presented.
We have some combination of these plus the mailing list
with our music software. I think the documentation
is pretty darn good, and in particualr, I believe *all* of the
functionality is documented at some level, which is
very important. I for one appreciate the efforts
of our documentors.
With time one hopes that repeated queries on the mailing
lists are moved into documentation. One also hopes
that people read the documentation, but as a writer
of documentation, I know that this is not always the case
(and of course language can be a bother here) !
cheers
Neil
_______________________________________________
TeX-music mailing list
[EMAIL PROTECTED]
http://sunsite.dk/mailman/listinfo/tex-music
