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

[Timo Sirainen]

On Mon, 2013-03-18 at 10:33 -0500, 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.

Because it significantly increases development times, and when you're
basically doing everything yourself there's nobody else reading those
anyway.

The more complex a feature is, the more I think about it, do pseudo code
and testing. For example the redesigned dsync in v2.2 required months of
thinking, pseudo coding and testing. Few features in Dovecot are that
complex though. Mostly coding is the easy part, while figuring out how
the configuration should be done is the difficult part.

Anyway, the plan is to hire more Dovecot developers and the development
process is likely to change then. But now? I'm way too busy implementing
things that were supposed to be finished half a year ago.

> 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

So basically you're saying that the major documentation improvement = an
index listing/describing all settings. Sure, would be useful, but I
don't see having time to write that anytime soon.