From: Derrick 'dman' Hudson (no email)
Date: Fri Aug 01 2003 - 16:49:43 EDT
On Fri, Aug 01, 2003 at 04:20:02PM -0400, Chateauneuf wrote:
| On Fri, 2003-08-01 at 16:06, Wietse Venema wrote:
|
| > The Postfix documentation is not for beginners. It requires that
| > people have mastered the art of reading arcane UNIX manual pages,
| > and it requires that people are familiar with basic UNIX concepts
| > such as <filename.
| That Unix documentation is generally arcane is not a virtue.
I really don't think 'arcane' is an accurate description. There isn't
anything hidden or secret about the man pages. (see below)
| Nor should that serve as a model for application documentation.
Sure it should: UNIX manpages are designed as reference documentation
for a technically literate audience. They aren't designed as a
tutorial. I certainly don't want a tutorial as the only
documentation, so that if I forget some details on a command line
option or file format I have to read a book to find it. There *are*
tutorial-style books available on the market which provide an
introduction to the concepts of UNIX and the (basic/common) commands
available. If you need an introduction, obtain an introductory text.
If you want a handy reference, use the manpage. (as an additional
note, not only is the core UNIX system documented in tutorial-style
prose, but so are many other systems built on it. In fact, Ralf has
just such a book devoted to postfix in the works :-).)
| Additionally, while the target audience may be professional that should
| not be cause for the documentation to be unnecessarily complex,
| inconsistent, contradictory, disjointed or insufficiently cross
| referenced.
Indeed.
| If you don't want to make that investment in your product then hire a
| professional to do it for you. ;-) You had that one coming (LOL).
That would be a good suggestion, if this was a commercial product :-).
As it is, Wietse doesn't need any documentation as long as his work
Works For Him ;-). The fact that he did take the time to document it
as extensively as he has is much better than a lot of OSS projects.
(this isn't to say, though, that the docs are perfect)
| Actually, I may volunteer to help out on this front if I have time this
| fall and if you want someone to do that to begin with.
That sounds good.
-D
--
[Perl] combines all the worst aspects of C and Lisp: a billion different
sublanguages in one monolithic executable.
It combines the power of C with the readability of PostScript.
-- Jamie Zawinski
http://dman13.dyndns.org/~dman/
|
|
|