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

[Joseba Torre]

El 19/03/13 05:15, Stan Hoeppner escribió:
> 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.

Definitely, something like man 5 postconf would be really useful. I 
would like to collaborate with that, but I think that my English writing 
skill are not good enough.
>