[Dovecot] Dovecot MTA

[Larry Stone]

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 at 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 at stonejongleux.com