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.
- Create man(ual) documentation, preferably with
- A man page like postconf (5) which contains every single Dovecot configuration parameter and text explaining it
- This man page published online
- Publish sample conf file(s) online
- 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.