[Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot

[Larry Stone]

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