On 2012-07-22 11:39, Hans J. Albertsson wrote:
To the point: Explain what you are going to demonstrate, and explain to what extent it can or cannot serve as a boiler-plate for more advanced configs. Complete ( in the appropriate manner ): For every single thing you display, explain what the reader is supposed to do about it, and make sure you explain what is going to appear automagically and what the reader must do to achieve what won't appear as a result of dovecot's own actions. Do not point the reader to other docs unless those docs agree with the current one in both form and perspective. If they don't, copy in and adjust to fit the current doc.
And also, make sure that if you write in english, the meaning of your words in absolutely unequivocal, there must not appear in any reader's mind the slightest doubt as to how (s)he's supposed to use the info given.
As an example, to wit, in the http://wiki2.dovecot.org/SharedMailboxes/Public doc, there's a line
"In the above example, you would then create Maildir mailboxes under the /var/mail/public/ directory."
and a colour plate plate showing a directory listing.
# ls -la /var/mail/public/ drwxr-s--- 1 root mail 0 2007-03-19 03:12 . drwxrws--- 1 root mail 0 2007-03-19 03:12 .lkml drwxrws--- 1 root mail 0 2007-03-19 03:12 .bugtraq -rw-rw---- 1 root mail 0 2007-03-19 03:12 dovecot-shared
I am guessing that this means I'm supposed to do mkdir dovecot-shared inside /var/mail/public.
But "creating Maildir mailboxes" might mean more than just mkdir, and not explaining that bit at this point in the doc slows the reader down, especially if (s)he's not already well versed in the mysteries of dovecot wizardry. And if (s)he is that, why should (s)he read the doc at all?
Sorry if I'm being horridly difficult, but I think (from experiencing it as a user) dovecot is too good not to have proper tutorials and howtos.