On Mon, 11 Nov 2013, Rob Sterenborg (lists) wrote:
On 11/10/2013 08:04 PM, Timo Sirainen wrote:
On 10.11.2013, at 20.00, Daniele Nicolodi daniele@grinta.net wrote:
Additionally I feel that Dovecot documentation can see some love as well. Having the wiki as main source of documentation does not look very polished, compared, for example to the extremely good written and maintained Postfix documentation.
I don?t know how to improve the current documentation. (Other than implementing the few missing man pages.) There is going to be a Dovecot book soon though, maybe that?ll help.
How Dovecot documentation can be improved? Well, what I find extremely helpful from the Postfix documentation but cannot find the equivalent for Dovecot is: http://www.postfix.org/postconf.5.html
Wiki's are helpful, but a full list of all configuration parameters, how they work and, when applicable, how they are related to other parameters will likely help a lot of users.
My experience is wiki's and a lot of equivalent are sort of a scattershot approach to deal with specific issues. They don't work well as the formal documentation.
I'd like to see one structured manual that starts at a high level and works its way down into the details. I tend to be someone who likes to skim documentation looking for what I need. As a result, I'm not a fan of documentation that consists of lots of links elsewhere since that's difficult to skim.
Ideally, this structured manual would start with an overview of what Dovecot is and its major components (I consider the IMAP/POP server a separate component from the Dovecot LDA as each can be used independent of the other). From there more detail about each of the major components and how to use and configure them. From there, even more detail as needed.
In a note a few days ago, I said I don't know enough about Dovecot to write new documentation. But I realized there is an area I can help with which is reviewing it to help make sure it makes sense even to the neophyte. Review it and provide feedback to the author along the lines of "I have no clue what this means" where appropriate.
I think one of the problems that plagues documentation everywhere is a tendency to assume knowledge that the reader doesn't have. When you're too close to a project, you tend to forget that everyone doesn't know what you know. It's something I am sometimes guilty of in my full-time job when I send out an email saying something needs to be a priority without explaining why it needs to be a priority (assuming the recipient knows the why).
Writing good documentation is hard, no question about it. And it is very overlooked and undervalued many places.
-- Larry Stone lstone19@stonejongleux.com