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 <dani...@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
lston...@stonejongleux.com
