[Dovecot] Documentation

[Kris Boyle]

On Mon, 2005-07-25 at 12:10, Enrique Perez-Terron wrote:

I've just set up Dovecot and I think there is some definite need
on the "guidance side" of Dovecot.  A number of my comments likely
sit in the "why would you set up an IMAP server in the first place"
category but here's my 2 cents worth (warning - that's Canadian money
;-)

> > I've been thinking of doing some major wiki restructuring some day
> > before v1.0 release. So that in main page there would be something like:
> >
> > 1. Information about IMAP, POP3, SMTP and mail servers in general

The Dovecot Wiki shouldn't rephrase what is out there in the big wild
Interweb.  I think it should be focused on an initial sort of question
and answer session that filters out people where IMAP isn't the
solution they are really looking for.  If you can't get to IMAP there 
isn't much point in considering Dovecot.  As more and more people start
to set up email server systems rather than email client systems at home,
there is a need for something that says "this is the wrong path".  So,
to move this from the abstract to almost the marketing side, possibly
these are things that should be directly accessible on the Wiki:

- how does your email show up on your email client?
  - drop the MTA, MDA, etc. stuff, most people don't understand it
  - provide links to web sites that provide this info in a useful
    fashion
- why do you think an IMAP solution is the way for you?
  - provide a couple of scenarios where IMAP is the right solution and
    maybe a couple where it is the wrong solution:
    - 1 - external access to a work IMAP server
    - 2 - small home network where it has become a PIA to have email
          POP'd down to local clients and then it resides on one
          computer and the email is inaccessible from another computer.
    - 3 - small business which is kinda like (2) but the business needs
          to backup all email (incoming and outgoing) for accountability
          reasons.
    - 4 - web access to local server email
          - doe's the implementer understand firewalls and DMZ's
    - 5-998 - put your email situation in here (and I don't think I
              have reserved enough numbers ;-)
    - 999 - IMAP is cool and I am going to do it no matter what ;-)

> > 2. Installing and setting up a simple Dovecot installation

I think this is pretty well handled in the doc's and the Wiki.  The
problem is when someone is trying to do something that is just a bit
off the norm and doesn't understand the implications.  Running ANY
server is something that you need to consider on a security level and
IMAP and Dovecot's implementation thereof are no different.

> > 3. Full guide to setting up a new system

This could be difficult - what is the "new" system expected to do? 
Dovecot and thereby IMAP are not a silver bullet, let's make sure that
people don't try to misapply an available technology because of the
"acronym of the day" syndrome.

> > 4. Migration from existing systems
> >  - other servers
> >  - mbox <-> maildir
> >  - pop3 -> imap

- other servers - the mailing list handles this pretty well.  Dovecot
is not "shrinkwrap" software so if someone is trying to move from 
another IMAP environment to Dovecot just point them to the mailing
list.  That said - generic lessons learned as already exist on the
Wiki should be kept up to date but someone already running IMAP is aware
of the possibility of inconsistencies between IMAP implementations and
should be looking for a "harder" resource than the Wiki - like the
mailing list.
- mbox <-> maildir - I should just shut up here, really...  I like
the fact that Dovecot claims to be agnostic on this issue.  It is
quite happy to work with either (I assume because I am an mbox guy
running very small (100+ emails a day).  Whaddya like better vi or
emacs?  Let's not start a conflict here unless Dovecot actually does
work better with one or the other.  In that case state the fact (and
it may require a scaling factor - less than X emails per day it doesn't
matter but after that you might be better off with one approach or
another).  A mini-FAQ that provides migration hints would be a good
thing.
- pop3 -> IMAP - I think this is back into my question about "why are
you doing this in the first place".

> > 5. Troubleshooting

Common Dovecot problems - yes.  Getting IMAP going in general, no. As
much as one stop shopping seems to be a good idea, it isn't.  If the
troubleshooting gets into "why are you doing this anyway" then it has
gone far afield and will chew up resources that are better spent 
advancing Dovecot rather than arguing whether IMAP is a good thing or
not.

> > 6. Supported features / current status / TODO

Mailing list - weekly emails on status.  You'll get the people who
care.  Wiki - one page on committed plans, another page that is a
filtered version of "things I am thinking about - if you want to
know more join the mailing list and pipe up there ..."

Other issues - Encourage all Dovecot users to update Wiki for how
they are using Dovecot with getmail/fetchmail/qmail/procmail and
friends. The Wiki needs more example implementations and that has to
come from the Dovecot user base.

New page for the Wiki - Well, I got here because I am concerned about
SPAM/virus/etc.  How does Dovecot fit in?  This goes back to the
previous paragraph (as well as the "why are you here in the first place
stuff"_ - USERS - how is your system setup?  I personally pre-filter
before anything hits my incoming spool.  Works well in my small scale
environment but I am sure others have different approaches.

Cheers,
As you can tell I am fully behind Dovecot and really appreciate
the effort expended in giving me such a wonderful tool.  Oh, yeah,
it's fully AMD64 functional if you didn't already know ;-).

Kris

-- 
====================================================================
Kris at Home ...    (\
                      \_@         
           ____________\/)_____________
~~-^~~-^~~-\____________\_____________/^~~-^~~-^~~-^~~-^~~-
^~~-^~~-^~~-^~~-^~~-^~~- \^~~-^~~-^~~-^~~-^~~-^~~-^~~-^~~-
~-^~~-^~~-^~~-^~~-^~~-^~~(\^~~-^~~-^~~-^~~-^~~-^~~-^~~-^~

====================================================================