[Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
Larry Stone
lstone19 at stonejongleux.com
Mon Mar 18 18:32:58 EET 2013
On Mon, 18 Mar 2013, Stan Hoeppner wrote:
> On 3/17/2013 3:50 PM, Timo Sirainen wrote:
>
>> It's the best I can do myself. I have no idea how they could be
>> improved in any major way. They say that the software developer himself
>> is the worst possible person to write its documentation, because he
>> can't understand what others find difficult..
>
> I don't know who "they" is. Wietse writes all the Postfix documentation
> himself. It comes naturally when one performs formal software
> development, not ad hoc, because documentation precedes coding. I would
> assume you do ad hoc development like most 20 somethings, coding on the
> fly when you get an idea, no formal definitions, no flow charting, no
> pseudo code, etc. Correct? If so this is 99% of the reason the
> documentation suffers, and this is typical of today's crop of young
> developers, unfortunately.
>
> For highly technical material the author is the only person qualified to
> write the docs. Having a 3rd party do it has a prerequisite of a Vulcan
> mind meld. Otherwise you talk and they type, which is slower than you
> doing it yourself.
Software needs two types of documentation. It needs overview type
documentation that describes what it is. This is for the person who is
looking for a product and has no idea if this specific product can meet
the need.
Second, it needs reference documentation that provides syntax for
commands, config files, and the like. This is for the person who is or
will be using the product and needs the details to use it properly for the
need.
Somewhere in between is documentation that point the user to the right
reference section. Providing detailed documentation of a command is
worthless if nothing tells me that that command is what I should use for
my need.
The reference documentation may well best be written by the software
author who knows exactly what syntax, etc. is needed. It's also
relatively (and I emphasize "relatively") easy since it can be done as you
go.
But the overview documentation may well best be written by someone who
knows nothing about it. The expert writing overview documentation may
assume the reader knows things he doesn't. It can make sense to the author
but leaves the reader without a clue as to what is being discussed. When
the author is someone unfamiliar with the product, he asks questions until
it makes sense and there is less tendancy for the documentation to assume
knowledge by the reader that is not there.
Overview documentation is a lot tougher to write well and it needs someone
with good writing skills (not good programming skills). Particularly in
the open-source world where enhancements can come quickly, it can be out
of date as soon as it's written.
-- Larry Stone
lstone19 at stonejongleux.com
More information about the dovecot
mailing list