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

[Stan Hoeppner]

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.

A few things could improve the current docs in a major way.

1.  Create man(ual) documentation, preferably with
2.  A man page like postconf (5) which contains every single
    Dovecot configuration parameter and text explaining it
3.  This man page published online
4.  Publish sample conf file(s) online
5.  Make these things accessible from the main Dovecot page,
    not buried down in the index hierarchy

I've always perceived the dovecot wiki docs with the hierarchical book,
chapter, verse, mini how-to layout as a dessert you assemble from the
buffet--a little cake, some pudding, a dab of whipped cream, chopped
nuts, and a cherry on top.  You end up with a dessert, empty calories,
not a complete meal.  You can't get full and keep going back, assembling
another dessert each time.

Typical UNIX documentation is steak and potatoes, veggies, and a dinner
roll.  You sit down, eat, and you're full.  No running around collecting
your food as you've got everything you need on one plate, and it's a
complete meal.

-- 
Stan