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