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.
