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

[Stan Hoeppner]

On 3/18/2013 11:37 AM, Timo Sirainen wrote:

> 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.

The time issue is perfectly understandable Timo.

My suggestion may not be the gold or platinum improvement to the docs,
but I think it would help a lot of people, especially since most using
Dovecot are also using Postfix, and since man is the standard UNIX
documentation format/interface.  I think some similarity/consistency
would help quite a bit as many people are so used to this format.

Do you have a way to simply dump all the current conf file parameter
names from 2.x into a single column text file?  I'll sort it and start
adding the legal parameter values and writing the parameter definitions
from information currently available in source and wiki pages.  When I
hit the point I can't find reference material for the rest of the
parameters, we can dump it to a wiki page or similar so others with the
knowledge can jump in and help finish it.  Once it's done, myself, or
someone else if they already have the experience, can create the man
page from this to be included in the source.  And you can create an
update mechanism/batch process so that updating the 'master' document
automatically updates the source man page and other published versions,
making documentation updates simple when you add/change parameters.

We could do the wiki bazaar style editing from the beginning, but I'd
rather not.  I'd like to get it started with a framework/layout and
style of prose typical of UNIX documentation, for other editors to
follow.  The definition text prose needs to be consistent all the way
through, or readers may be confused by the different writing styles of
~50 different people who may speak different 'dialects' of English or
have different writing styles.  This consistency is one of the hallmarks
of good technical writing.

Like I said previously, the one thing I'm able to contribute more than
anything at this point is time.  And my writing skills aren't completely
horrible--I have been published, FWIW, but not recently.  But my
knowledge of the parameters, and a lot of Dovecot features in general is
lacking.  So if others are willing to contribute where I fall short, I'd
be glad to give this a go and get it started, and hopefully put a decent
sized dent in it so there's not so much left for others to do.
Obviously you have final review/edit authority, and if you have a
particular preference on writing style, etc, I'll certainly honor that.

If this is acceptable to you Timo, let me know.  If so send me the
aforementioned file, any preferences/thoughts you have, and I'll get
started on the first draft.

-- 
Stan