14 files changed, 618 insertions, 476 deletions
diff --git a/src/mailman/config/docs/config.rst b/src/mailman/config/docs/config.rst
index af9b35061..16c3d40bc 100644
--- a/src/mailman/config/docs/config.rst
+++ b/src/mailman/config/docs/config.rst
@@ -1,6 +1,8 @@
-=======================
- Mailman Configuration
-=======================
+.. _configuration:
+
+=====================
+ Configuring Mailman
+=====================
 
 This is Mailman's default configuration, directly included from the source
 code.  The format is standard "ini"-style.
@@ -30,10 +32,10 @@ You will need to restart Mailman for any changes to take effect.
 schema.cfg
 ==========
 
-``schema.cfg`` includes templates for several configuration options that are
-instantiated inside of ``mailman.cfg``.  Sections that are named with a suffix
-of ``.master`` or ``.template`` (e.g. ``paths.master``) are "template"
-sections which require an instantiation in ``mailman.cfg`` [#]_.
+``schema.cfg`` defines the ini-file schema and contains documentation for
+every section and configuration variable.  Sections that are named with a
+suffix of ``.master`` or ``.template`` (e.g. ``paths.master``) are "template"
+sections which must be defined in the ``mailman.cfg`` file [#]_.
 
 .. literalinclude:: ../schema.cfg
 
diff --git a/src/mailman/docs/ACKNOWLEDGMENTS.rst b/src/mailman/docs/ACKNOWLEDGMENTS.rst
index 0b1e6246a..ab45395c4 100644
--- a/src/mailman/docs/ACKNOWLEDGMENTS.rst
+++ b/src/mailman/docs/ACKNOWLEDGMENTS.rst
@@ -46,41 +46,41 @@ Copyright Assignees
 Here is the list of other contributors who have donated large bits of
 code, and have assigned copyright for contributions to the FSF:
 
-* Juan Carlos Rey Anaya
+* Andreas Schosser
 * Andrija Arsic
-* Richard Barrett
+* Ben Gertzfield
+* Cedric Knight
+* Claudia Schmidt
+* Ethan Mindlace Fremen
 * Jimmy Bergman
-* Stephan Berndts
-* Norbert Bollow
 * Joe Dugan
-* Ethan Mindlace Fremen
-* Ben Gertzfield
-* Victoriano Giralt
-* Stephen Goss
+* Juan Carlos Rey Anaya
+* Les Niles
 * Mads Kiilerich
-* Cedric Knight
+* Norbert Bollow
 * Patrick Ben Koetter
-* The Dragon De Monsyne
-* Les Niles
 * Reed O'Brien
-* Terri Oda
-* Simone Piunno
-* Claudia Schmidt
-* Andreas Schosser
+* Richard Barrett
 * Richard Wackerbarth
+* Simon Hanna
+* Simone Piunno
+* Stephan Berndts
+* Stephen Goss
+* The Dragon De Monsyne
+* Victoriano Giralt
 
 
 Special Thanks
 ==============
 
-Very special thanks to Andrija Arsic for his winning new GNU Mailman logos.
+Very special thanks to Andrija Arsic for his winning GNU Mailman logos.
 
 Thanks also go to the following people for their important contributions in
 other aspects of the Mailman project:
 
 * Brad Knowles
-* JC Dill
 * Clytie Siddall
+* JC Dill
 
 Thanks also to Dragon for his original Mailman logo contribution, and to Terri
 Oda for the neat shortcut icon and the member documentation.
@@ -94,201 +94,241 @@ suggestions, bug fixes, testing, etc., or who have been very helpful in
 answering questions on mailman-users.  Please let me know if you have been
 left off the list!
 
-* David Abrahams
-* William Ahern
-* Terry Allen
-* Jose Paulo Moitinho de Almeida
-* Sven Anderson
-* Matthias Andree
-* Anton Antonov
-* Mike Avery
-* Stonewall Ballard
-* Moreno Baricevic
-* Jimmy Bergman
-* Jeff Berliner
-* Stuart Bishop
-* David Blomquist
-* Bojan
-* Søren Bondrup
-* Grant Bowman
+* "office"
+* Ademar de Souza Reis, Jr.
 * Alessio Bragadini
-* J\. D\. Bronson
-* Stan Bubrouski
-* Daniel Buchmann
+* Alexander Sulfrian
+* Andrew Kuchling
+* Andrew Martynov
+* Anti Veeranna
+* Anton Antonov
+* Antonis Limperis
+* Ashley M. Kirchner
+* Balazs Nagy
+* Bartosz Sawicki
 * Ben Burnett
-* Ted Cabeen
-* Mentor Cana
-* John Carnes
-* Julio A. Cartaya
-* Claudio Cattazzo
-* Donn Cave
-* David Champion
-* Hye-Shik Chang
-* Eric D. Christensen
-* Tom G. Christensen
-* Paul Cox
-* Stefaniu Criste
-* Robert Daeley
-* Ned Dawes
-* Emilio Delgado
-* John Dennis
-* Stefan Divjak
-* Maximillian Dornseif
-* Fred Drake
-* Maxim Dzumanenko
-* Piarres Beobide Egaña
-* Rob Ellis
-* Kerem Erkan
-* Fil
-* Patrick Finnerty
+* Bernhard Reiter
+* Bernhard Schmidt
+* Bert Hubert
+* Bill Wagner
+* Blair Zajac
 * Bob Fleck
-* Erik Forsberg
-* Darrell Fuhriman
-* Robert Garrigós
+* Bob Puff
+* Bojan
+* Cabel Sasser
 * Carson Gaspar
-* Pascal GEORGE
-* Vadim Getmanshchuk
+* Chris Kolar
+* Chris Pepper
+* Chris Ryan
+* Chris Snell
+* Christian F Buser
+* Christian Reis
+* Christopher P. Lindsey
+* Chuq Von Rospach
+* Claudio Cattazzo
+* Dai Xiaoguang
+* Dale Newfield
+* Dale Stimson
+* Dan Mick
+* Dan Ohnesorg
+* Dan Wilder
+* Daniel Buchmann
+* Daniel Zeiss
+* Danil Smirnov
+* Danny Terweij
+* Dario Lopez-Kästen
+* Darrell Fuhriman
+* David Abrahams
+* David B. O'Donnell
+* David Blomquist
+* David Champion
 * David Gibbs
+* David Habben
+* David Martínez Moreno
+* David Soto
+* David T-G
+* Diego Francisco de Gastal Morales
+* Dirk Mueller
 * Dmitri I GOULIAEV
-* Terry Grace
+* Don Porter
+* Donn Cave
+* Ed Lau
+* Eddie Kohler
+* Egon Frerich
+* Emerson Ribeiro de Mello
+* Emilio Delgado
+* Eric D. Christensen
+* Erik Forsberg
+* Erik Myllymaki
+* Eva Österlind
+* Fabian Wenk
 * Federico Grau
-* Pekka Haavisto
-* David Habben
-* Stig Hackvan
-* Jeff Hahn
-* Terry Hardie
-* Paul Hebble
-* Tollef Fog Heen
-* Peer Heinlein
-* James Henstridge
-* Walter Hop
-* Bert Hubert
+* Fil
+* Florian Weimer
+* Francesco Potortì
+* Francis Jorissen
+* Franck Martin
+* Fred Drake
+* Gabriel P. Silva
+* Garey Mills
+* Gari Araolaza
+* Geoff Mayes
+* Gerald Oskoboiny
+* Gergely Madarasz
+* Gleydson Mazioli da Silva
+* Grant Bowman
+* Greg Lindahl
+* Greg Stein
+* Greg Ward
+* Guido van Rossum
+* Harald Koch
+* Heiko Rommel
 * Henny Huisman
-* Jeremy Hylton
+* Hrvoje Niksic
+* Hugo Koji Kobayashi
+* Hye-Shik Chang
 * Ikeda Soji
-* Rostyk Ivantsiv
-* Ron Jarrell
-* Matthias Juchem
-* Tamito KAJIYAMA
-* Nino Katic
-* SHIGENO Kazutaka
-* Ashley M. Kirchner
-* Matthias Klose
-* Harald Koch
-* Patrick Koetter
-* Eddie Kohler
-* Chris Kolar
-* Uros Kositer
-* Andrew Kuchling
-* Ricardo Kustner
-* L'homme Moderne
-* Sylvain Langlade
-* Ed Lau
 * J C Lawrence
-* Greg Lindahl
-* Christopher P. Lindsey
-* Martin von Loewis
-* Dario Lopez-Kästen
-* Tanner Lovelace
+* J. D. Bronson
+* James Henstridge
+* Jan Veuger
+* Jason R. Mastaler
+* Javad Hoseini
+* Javier Rial Rodríguez
 * Jay Luker
-* Gergely Madarasz
-* Luca Maranzano
+* Jeff Berliner
+* Jeff Hahn
+* Jens Vagelpohl
+* Jeremy Hylton
+* Jim Popovitch
+* Jim Tittsler
+* Jimmy Bergman
+* Joe Peterson
 * John A. Martin
-* Andrew Martynov
-* Jason R. Mastaler
-* Michael Mclay
-* Michael Meltzer
+* John Carnes
+* John Dennis
+* John Read
+* Jon Parise
+* Jonas Muerer
+* Jonas Smedegaard
+* Joni Töyrylä
+* Jose Paulo Moitinho de Almeida
+* Julio A. Cartaya
+* Kai Schaetzl
+* Karl Chen
+* Karoly Segesdi
+* Kathleen Webb
+* Kerem Erkan
+* Kleber A. Benatti
+* L'homme Moderne
+* Les Niles
+* Lindsay Haisley
+* Lionel Elie Mamane
+* Luca Maranzano
+* Luigi Rosa
+* Mahyar Moghimi
 * Marc MERLIN
-* Nigel Metheringham
-* Dan Mick
-* Garey Mills
+* Marcos Costales
+* Mark Weaver
+* Martijn Dekker
+* Martin 'Joey' Schulze
+* Martin Matuska
 * Martin Mokrejs
+* Martin Pool
+* Martin von Loewis
+* Matthias Andree
+* Matthias Juchem
+* Matthias Klose
+* Maxim Dzumanenko
+* Maxime Carron
+* Maximillian Dornseif
+* Mentor Cana
 * Michael Fischer v. Mollard
-* David Martínez Moreno
-* Dirk Mueller
-* Jonas Muerer
-* Erik Myllymaki
-* Balazs Nagy
-* Moritz Naumann
-* Dale Newfield
-* Hrvoje Niksic
-* Les Niles
+* Michael Mclay
+* Michael Meltzer
+* Michael Ranner
+* Michael Yount
+* Mike Avery
 * Mike Noyes
-* David B. O'Donnell
-* Timothy O'Malley
-* "office"
-* Dan Ohnesorg
-* Gerald Oskoboiny
-* Eva Österlind
-* Toni Panadès
-* Jon Parise
-* Chris Pepper
-* Tim Peters
-* Joe Peterson
+* Mikhail Sobolev
+* Mikhail Zabaluev
+* Miloslav Trmac
+* Mirian Margiani
+* Moreno Baricevic
+* Moritz Naumann
+* Ned Dawes
+* Nicholas Russo
+* Nigel Metheringham
+* Nino Katic
+* Noam Zeilberger
+* Ousmane Wilane
+* Owen Taylor
+* Pascal GEORGE
+* Pasi Sjöholm
+* Patrick Finnerty
+* Patrick Koetter
+* Paul Cox
+* Paul Hebble
+* Peer Heinlein
+* Pekka Haavisto
+* Phil Pennock
+* Piarres Beobide Egaña
 * PieterB
+* Ping Yeh
+* Ralf Doeblitz
+* Ralf Hildebrandt
+* Ricardo Kustner
+* Rob Ellis
+* Robert Daeley
+* Robert Garrigós
 * Rodolfo Pilas
-* Skye Poier
-* Martin Pool
-* Don Porter
-* Francesco Potortì
-* Bob Puff
-* Abhilash Raj
-* Michael Ranner
-* John Read
+* Roger Tsang
+* Ron Jarrell
+* Rostyk Ivantsiv
+* SATOH Fumiyasu
+* SHIGENO Kazutaka
 * Sean Reifschneider
-* Christian Reis
-* Ademar de Souza Reis, Jr.
-* Bernhard Reiter
+* Seb Wills
+* Skye Poier
+* Stan Bubrouski
+* Stefan Divjak
+* Stefan Förster
+* Stefan Plewako
+* Stefaniu Criste
 * Stephan Richter
-* Tristan Roddis
-* Heiko Rommel
-* Luigi Rosa
-* Guido van Rossum
-* Nicholas Russo
-* Chris Ryan
-* Cabel Sasser
-* Bartosz Sawicki
-* Kai Schaetzl
-* Karoly Segesdi
-* Gleydson Mazioli da Silva
-* Pasi Sjöholm
-* Chris Snell
-* Mikhail Sobolev
-* David Soto
-* Greg Stein
-* Dale Stimson
+* Stig Hackvan
+* Stonewall Ballard
+* Stuart Bishop
 * Students of HIT <mailman-cn@mail.cs.hit.edu.cn>
-* Alexander Sulfrian
+* Sven Anderson
+* Sylvain Langlade
 * Szabolcs Szigeti
-* Vizi Szilard
-* David T-G
-* Owen Taylor
-* Danny Terweij
-* Jim Tittsler
+* Søren Bondrup
+* Tamito KAJIYAMA
+* Tanner Lovelace
+* Ted Cabeen
+* Terry Allen
+* Terry Grace
+* Terry Hardie
+* Thijs Kinkhorst
+* Tim Peters
+* Timothy O'Malley
 * Todd (Freedom Lover)
-* Roger Tsang
-* Chuq Von Rospach
-* Jens Vagelpohl
-* Valia V. Vaneeva
-* Anti Veeranna
 * Todd Vierling
-* Bill Wagner
-* Greg Ward
-* Mark Weaver
-* Kathleen Webb
-* Florian Weimer
-* Ousmane Wilane
-* Dan Wilder
-* Seb Wills
-* Dai Xiaoguang
-* Ping Yeh
-* YASUDA Yukihiro
-* Michael Yount
-* Blair Zajac
-* Mikhail Zabaluev
-* Noam Zeilberger
-* Daniel Zeiss
 * Todd Zullinger
+* Tollef Fog Heen
+* Tom G. Christensen
+* Tomasz Chmielewski
+* Toni Panadès
+* Tristan Roddis
+* Uros Kositer
+* Vadim Getmanshchuk
+* Valia V. Vaneeva
+* Vizi Szilard
+* Walter Hop
+* William Ahern
+* YASUDA Yukihiro
+* Yasuhito FUTATSUKI
 
 And everyone else on mailman-developers@python.org and
 mailman-users@python.org!  Thank you, all.
diff --git a/src/mailman/docs/STYLEGUIDE.rst b/src/mailman/docs/STYLEGUIDE.rst
index 503b98db5..d5bbdc1ae 100644
--- a/src/mailman/docs/STYLEGUIDE.rst
+++ b/src/mailman/docs/STYLEGUIDE.rst
@@ -1,17 +1,17 @@
-==============================
-GNU Mailman Coding Style Guide
-==============================
+================================
+ GNU Mailman Coding Style Guide
+================================
 
 Copyright (C) 2002-2017 Barry A. Warsaw
 
 
-Python coding style guide for GNU Mailman
-=========================================
+Python coding style guide for GNU Mailman Core
+==============================================
 
 This document contains a style guide for Python programming, as used in GNU
-Mailman.  `PEP 8`_ is the basis for this style guide so its recommendations
-should be followed except for the differences outlined here.  This document
-assumes the use of Python 3.
+Mailman Core.  `PEP 8`_ is the basis for this style guide so its
+recommendations should be followed except for the differences outlined here.
+Core is a Python 3 application, so this document assumes the use of Python 3.
 
 Much of the style guide is enforced by the command ``tox -e qa``.
 
@@ -19,8 +19,8 @@ Much of the style guide is enforced by the command ``tox -e qa``.
   an example.
 
 * Public module-global names should be exported in the ``__all__`` but use the
-  ``@public`` decorator from the top-level ``mailman`` package to do this for
-  all classes and functions.
+  ``@public`` decorator from the public_ package to do this for all classes
+  and functions.
 
 * Imports are always put at the top of the file, just after any module
   comments and docstrings, and before module globals and constants.
@@ -70,18 +70,19 @@ Much of the style guide is enforced by the command ``tox -e qa``.
              """
 
 * Write docstrings for modules, functions, classes, and methods.  Docstrings
-  can be omitted for special methods (e.g. __init__() or __str__()) where the
-  meaning is obvious.
+  can be omitted for special methods (e.g. ``__init__()`` or ``__str__()``)
+  where the meaning is obvious.
 
-* PEP 257 describes good docstrings conventions.  Note that most importantly,
-  the """ that ends a multiline docstring should be on a line by itself, e.g.::
+* `PEP 257`_ describes good docstrings conventions.  Note that most
+  importantly, the ``"""`` that ends a multiline docstring should be on a line
+  by itself, e.g.::
 
     """Return a foobang
 
     Optional plotz says to frobnicate the bizbaz first.
     """
 
-* For one liner docstrings, keep the closing """ on the same line.
+* For one liner docstrings, keep the closing ``"""`` on the same line.
 
 * ``fill-column`` for docstrings should be 78.
 
@@ -106,3 +107,5 @@ Much of the style guide is enforced by the command ``tox -e qa``.
 
 .. _`PEP 8`: http://www.python.org/peps/pep-0008.html
 .. _`GNU Mailman Python template`: https://gitlab.com/mailman/mailman/blob/master/template.py
+.. _public: https://public.readthedocs.io/en/latest/
+.. _`PEP 257`: http://www.python.org/peps/pep-0257.html
diff --git a/src/mailman/docs/ARCHITECTURE.rst b/src/mailman/docs/architecture.rst
index 3208ec842..e1d5c4ec5 100644
--- a/src/mailman/docs/ARCHITECTURE.rst
+++ b/src/mailman/docs/architecture.rst
@@ -1,6 +1,6 @@
-======================
-Mailman 3 architecture
-======================
+=============================
+ Mailman 3 Core architecture
+=============================
 
 This is a brief overview of the internal architecture of the Mailman 3 core
 delivery engine.  You should start here if you want to understand how Mailman
@@ -49,9 +49,9 @@ Process model
 Messages move around inside the Mailman system by way of *queue* directories
 managed by the *switchboard*.  For example, when a message is first received
 by Mailman, it is moved to the *in* (for "incoming") queue.  During the
-processing of this message, it -- or copies of it -- may be moved to other
-queues such as the *out* queue (for outgoing email), the *archive* queue (for
-sending to the archivers), the *digest* queue (for composing digests), etc.
+processing of this message, it -or copies of it- may be moved to other queues
+such as the *out* queue (for outgoing email), the *archive* queue (for sending
+to the archivers), the *digest* queue (for composing digests), etc.
 
 A message in a queue is represented by a single file, a ``.pck`` file.  This
 file contains two objects, serialized as `Python pickles`_.  The first object
@@ -65,7 +65,7 @@ processed.
 
 Each queue directory is associated with a *runner* process which wakes up
 every so often.  When the runner wakes up, it examines all the ``.pck`` files
-in FIFO order, deserializing the message and metadata objects, processing
+in FIFO order, deserializing the message and metadata objects, and processing
 them.  If the message needs further processing in a different queue, it will
 be re-serialized back into a ``.pck`` file.  If not (e.g. because processing
 of the message is complete), then no ``.pck`` file is written.
@@ -87,10 +87,10 @@ Rules and chains
 When a message is first received for posting to a mailing list, Mailman
 processes the message to determine whether the message is appropriate for the
 mailing list.  If so, it *accepts* the message and it gets posted.  Mailman
-can also *discard* the message so that no further processing occurs.  Mailman
-can also *reject* the message, bouncing it back to the original sender,
-usually with some indication of why the message was rejected.  Mailman can
-also *hold* the message for moderator approval.
+can *discard* the message so that no further processing occurs.  Mailman can
+also *reject* the message, bouncing it back to the original sender, usually
+with some indication of why the message was rejected.  Or, Mailman can *hold*
+the message for moderator approval.
 
 *Moderation* is the phase of processing that determines which of the above
 four dispositions will occur for the newly posted message.  Moderation does
@@ -115,7 +115,7 @@ the appropriate start chain.  The message is then passed to the chain, where
 each link in the chain first checks to see if its rule matches, and if so, it
 executes the linked action.  This action is usually one of *accept*, *reject*,
 *discard*, and *hold*, but other actions are possible, such as executing a
-function or jumping to another chain.
+function, deferring action, or jumping to another chain.
 
 As you might imagine, you can write new rules, compose them into new chains,
 and configure a mailing list to use your custom chain when processing the
@@ -149,16 +149,40 @@ Of course, you can define new handlers, compose them into new pipelines, and
 change a mailing list's pipelines.
 
 
+Integration and control
+=======================
+
+Humans and external programs can interact with a running Core system in may
+different ways.  There's an extensive command line interface that provides
+useful options to a system administrator.  For external applications such as
+the Postorius web user interface, and the HyperKitty archiver, the
+`administrative REST API <rest-api>` is the most common way to get information
+into and out of the Core.
+
+**Note**: The REST API is an administrative API and as such it must not be
+exposed to the public internet.  By default, the REST server only listens on
+``localhost``.
+
+Internally, the Python API is extensive and well-documented.  Most objects in
+the system are accessed through the `Zope Component Architecture`_ (ZCA).  If
+your Mailman installation is importable, you can write scripts directly
+against the internal public Python API.
+
+
 Other bits and pieces
 =====================
 
-There are lots of other pieces to the Mailman puzzle, such as the REST API,
-the set of core functionality (logging, initialization, event handling, etc.),
-mailing list *styles*, the API for integrating external archivers and mail
-servers.  The database layer is an critical piece, and Mailman has an
-extensive set of command line commands, and email commands.
+There are lots of other pieces to the Mailman puzzle, such as the set of core
+functionality (logging, initialization, event handling, etc.), mailing list
+*styles*, the API for integrating external archivers and mail servers.  The
+database layer is an critical piece, and Mailman has an extensive set of
+command line commands, and email commands.
+
+Almost the entire system is documented in these pages, but it maybe be a bit
+of a spelunking effort to find it.  Improvements are welcome!
 
 
 .. _`Architecture of Open Source Applications`: http://www.aosabook.org/en/mailman.html
 .. _`Python pickles`: http://docs.python.org/2/library/pickle.html
 .. _`more efficient internal representation`: https://docs.python.org/3/library/email.html
+.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
diff --git a/src/mailman/docs/CONTRIBUTE.rst b/src/mailman/docs/contribute.rst
index af76b9956..136a4460d 100644
--- a/src/mailman/docs/CONTRIBUTE.rst
+++ b/src/mailman/docs/contribute.rst
@@ -1,46 +1,10 @@
-.. _start-here:
-
-=========================
-Contributing to Mailman 3
-=========================
+===========================
+ Contributing to Mailman 3
+===========================
 
 Copyright (C) 2008-2017 by the Free Software Foundation, Inc.
 
 
-Contact Us
-==========
-
-Contributions of code, problem reports, and feature requests are welcome.
-Please submit bug reports on the Mailman bug tracker at
-https://gitlab.com/mailman/mailman/issues (you need to have a login on GitLab
-to do so).  You can also send email to the mailman-developers@python.org
-mailing list, or ask on IRC channel ``#mailman`` on Freenode.
-
-
-Requirements
-============
-
-For the Core, Python 3.4 or newer is required.  It can either be the default
-'python3' on your ``$PATH`` or it can be accessible via the ``python3.4`` or
-``python3.5`` binary.  If your operating system does not include Python 3, see
-http://www.python.org for information about downloading installers (where
-available) and installing it from source (when necessary or preferred).
-Python 2 is not supported by the Core.
-
-You may need some additional dependencies, which are either available from
-your OS vendor, or can be downloaded automatically from the `Python
-Cheeseshop`_.
-
-
-Documentation
-=============
-
-The documentation for Mailman 3 is distributed throughout the sources.  The
-core documentation (such as this file) is found in the ``src/mailman/docs``
-directory, but much of the documentation is in module-specific places.  Online
-versions of the `Mailman 3 Core documentation`_ is available online.
-
-
 How to contribute
 =================
 
@@ -51,6 +15,18 @@ to sign a `copyright assignment`_ to the Free Software Foundation, the owner
 of the GNU Mailman copyright.  If you'd like to jump start your copyright
 assignment, please contact the GNU Mailman `steering committee`_.
 
+Please read the :doc:`STYLEGUIDE` for required coding style guidelines.
+
+
+Contact Us
+==========
+
+Contributions of code, problem reports, and feature requests are welcome.
+Please submit bug reports on the Mailman bug tracker at
+https://gitlab.com/mailman/mailman/issues (you need to have a login on GitLab
+to do so).  You can also send email to the mailman-developers@python.org
+mailing list, or ask on IRC channel ``#mailman`` on Freenode.
+
 
 Get the sources
 ===============
@@ -72,10 +48,10 @@ To run the Mailman test suite, just use the `tox`_ command::
 
     $ tox
 
-`tox` creates a virtual environment (virtualenv) for you, installs all the
+`tox` creates a virtual environment (virtualenv_) for you, installs all the
 dependencies into that virtualenv, and runs the test suite from that
 virtualenv.  By default it does not use the `--system-site-packages` so it
-downloads everything from the Cheeseshop.
+downloads everything from the `Python Cheeseshop`_.
 
 A bare ``tox`` command will try to run several test suites, which might take a
 long time, and/or require versions of Python or other components you might not
@@ -84,40 +60,43 @@ available.  Very often, when you want to run the full test suite in the
 quickest manner with components that should be available everywhere, run one
 of these command, depending on which version of Python 3 you have::
 
-    $ tox -e py35
-    $ tox -e py34
+    $ tox -e py36-nocov
+    $ tox -e py35-nocov
+    $ tox -e py34-nocov
 
 You can run individual tests in any given environment by providing additional
 positional arguments.  For example, to run only the tests that match a
 specific pattern::
 
-    $ tox -e py35 -- -P user
+    $ tox -e py35-nocov -- -P user
 
 You can see all the other arguments supported by the test suite by running::
 
-    $ tox -e py35 -- --help
+    $ tox -e py35-nocov -- --help
 
 You also have access to the virtual environments created by tox, and you can
 use this run the virtual environment's Python executable, or run the
 ``mailman`` command locally, e.g.::
 
-    $ .tox/py35/bin/python
-    $ .tox/py35/bin/mailman --help
+    $ .tox/py35-nocov/bin/python
+    $ .tox/py35-nocov/bin/mailman --help
 
 If you want to set up the virtual environment without running the full test
 suite, you can do this::
 
-    $ tox -e py35 --notest -r
+    $ tox -e py35-nocov --notest -r
 
 
-Testing with  PostgreSQL
-========================
+Testing with PostgreSQL and MySQL
+=================================
 
 By default, the test suite runs with the built-in SQLite database engine.  If
-you want to run the full test suite against the PostgreSQL database, set the
-database up as described in :doc:`DATABASE`, then create a `postgres.cfg` file
-any where you want.  This `postgres.cfg` file will contain the ``[database]``
-section for PostgreSQL, e.g.::
+you want to run the full test suite against the PostgreSQL or MySQL databases,
+set the database up as described in :doc:`database`.
+
+For PostgreSQL, then create a `postgres.cfg` file any where you want.  This
+`postgres.cfg` file will contain the ``[database]`` section for PostgreSQL,
+e.g.::
 
     [database]
     class: mailman.database.postgresql.PostgreSQLDatabase
@@ -161,7 +140,14 @@ install.
 Building the documentation
 ==========================
 
-Build the online docs by running::
+To build the documentation, you need some additional dependencies.  The only
+one you probably need from your OS vendor is `graphiz`.  E.g. On Debian or
+Ubuntu, you can do::
+
+    $ sudo apt install graphiz
+
+All other dependencies should be automatically installed as needed.  Build the
+documentation by running::
 
     $ tox -e docs
 
@@ -170,53 +156,6 @@ Then visit::
     build/sphinx/html/index.html
 
 
-Running Mailman 3
-=================
-
-What, you actually want to *run* Mailman 3?  Oh well, if you insist.
-
-You will need to set up a configuration file to override the defaults and set
-things up for your environment.  Mailman is configured using an "ini"-style
-configuration system.
-
-``src/mailman/config/schema.cfg`` defines the ini-file schema and contains
-documentation for every section and configuration variable.  Sections that end
-in ``.template`` or ``.master`` are templates that must be overridden in
-actual configuration files.  There is a default configuration file that
-defines these basic overrides in ``src/mailman/config/mailman.cfg``.  Your own
-configuration file will override those.
-
-By default, all runtime files are put under a ``var`` directory in the current
-working directory.
-
-Mailman searches for its configuration file using the following search path.
-The first existing file found wins.
-
-* ``-C config`` command line option
-* ``$MAILMAN_CONFIG_FILE`` environment variable
-* ``./mailman.cfg``
-* ``~/.mailman.cfg``
-* ``/etc/mailman.cfg``
-* ``argv[0]/../../etc/mailman.cfg``
-
-Run the ``mailman info`` command to see which configuration file Mailman will
-use, and where it will put its database file.  The first time you run this,
-Mailman will also create any necessary run-time directories and log files.
-
-Try ``mailman --help`` for more details.  You can use the commands
-``mailman start`` to start the runner subprocess daemons, and of course
-``mailman stop`` to stop them.
-
-Postorius, a web UI for administration and subscriber settings, is being
-developed as a separate, Django-based project.  For now, the most flexible
-means of configuration is via the command line and REST API.
-
-Note that you can also "run" Mailman from one of the virtual environments
-created by tox, e.g.::
-
-    $ .tox/py35/bin/mailman info
-
-
 Mailman Shell
 =============
 
@@ -262,7 +201,7 @@ via the REST client API.  This architecture makes it possible for users with
 other needs to adapt the web UI, or even replace it entirely, with a
 reasonable amount of effort.  However, as a core feature of Mailman, the web
 UI emphasizes usability over modularity at first, so most users should use the
-web UI described here.  Postorius is a Django_ application.
+web UI described here.  Postorius_ is a Django_ application.
 
 
 The Archiver
@@ -276,28 +215,33 @@ is appropriate for that archiver.  Summary, search, and retrieval of archived
 posts are handled by a separate application.
 
 A new archive UI called `HyperKitty`_, based on the `notmuch mail indexer`_
-was prototyped at the PyCon 2012 sprint by Toshio Kuratomi.  The HyperKitty
+was prototyped at the `Pycon 2012 sprint`_ by Toshio Kuratomi.  The HyperKitty
 archiver is very loosely coupled to Mailman 3 core.  In fact, any email
 application that speaks LMTP or SMTP will be able to use HyperKitty.
 HyperKitty is also a Django application.
 
 
+REST API Python bindings
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mailman 3 provides a REST API for administrative purposes, and this is used by
+both HyperKitty and Postorius.  You can of course use any HTTP client to speak
+to it, but we provide official Python bindings (for both Python 2 and 3) in a
+package we call `mailman.client`_.
+
+
+.. _`merge requests`: https://gitlab.com/mailman/mailman/merge_requests
+.. _`bug reports`: https://gitlab.com/mailman/mailman/issues
+.. _`copyright assignment`: https://www.fsf.org/licensing/assigning.html/?searchterm=copyright%20assignment
+.. _`steering committee`: mailto:mailman-cabal@python.org
+.. _tox: https://testrun.org/tox/latest/
+.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
 .. _`Postorius`: https://gitlab.com/mailman/postorius
-.. _`HyperKitty`: https://gitlab.com/mailman/hyperkitty
 .. _`Django`: http://djangoproject.org/
-.. _`REST client module`: https://gitlab.com/mailman/mailmanclient
-.. _`Five Minute Guide the Web UI`: WebUIin5.html
-.. _`blog post`: http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running
+.. _`HyperKitty`: https://gitlab.com/mailman/hyperkitty
 .. _`notmuch mail indexer`: http://notmuchmail.org
-.. _`five minute guide to Hyperkitty`: ArchiveUIin5.html
+.. _`mailman.client`: https://gitlab.com/mailman/mailmanclient
 .. _`Pycon 2012 sprint`: https://us.pycon.org/2012/community/sprints/projects/
 .. _`Python Cheeseshop`: http://pypi.python.org/pypi
 .. _`virtualenv`: http://www.virtualenv.org/en/latest/
 .. _`pyvenv`: https://docs.python.org/3/library/venv.html
-.. _`Mailman 3 Core documentation`: https://mailman.readthedocs.io
-.. _tox: https://testrun.org/tox/latest/
-.. _`merge requests`: https://gitlab.com/mailman/mailman/merge_requests
-.. _`bug reports`: https://gitlab.com/mailman/mailman/issues
-.. _`copyright assignment`: https://www.fsf.org/licensing/assigning.html/?searchterm=copyright%20assignment
-.. _`steering committee`: mailto:mailman-cabal@python.org
-.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
diff --git a/src/mailman/docs/DATABASE.rst b/src/mailman/docs/database.rst
index c85731fb3..fc606a64d 100644
--- a/src/mailman/docs/DATABASE.rst
+++ b/src/mailman/docs/database.rst
@@ -1,10 +1,10 @@
-========================
-Setting up your database
-========================
+==========================
+ Setting up your database
+==========================
 
 Mailman uses the SQLAlchemy_ ORM to provide persistence of data in a
 relational database.  By default, Mailman uses Python's built-in SQLite3_
-database, however, SQLAlchemy is compatible with PostgreSQL_ and MySQL, among
+database, however, SQLAlchemy is compatible with PostgreSQL_ and MySQL_, among
 possibly others.
 
 Currently, Mailman is known to work with the SQLite3, PostgreSQL, and MySQL
@@ -26,8 +26,8 @@ As mentioned, if you want to use SQLite3 in the default configuration, you
 generally don't need to change anything.  However, if you want to change where
 the SQLite3 database is stored, you can change the ``url`` variable in the
 ``[database]`` section.  By default, the database is stored in the *data
-directory* in the ``mailman.db`` file.  Here's how you'd force Mailman to
-store its database in ``/var/lib/mailman/sqlite.db`` file::
+directory* in the ``mailman.db`` file.  Here's how to tell Mailman to store
+its database in ``/var/lib/mailman/sqlite.db`` file::
 
     [database]
     url: sqlite:////var/lib/mailman/sqlite.db
@@ -41,7 +41,7 @@ help.  Let's say you create the `mailman` database in PostgreSQL via::
 
     $ sudo -u postgres createdb -O $USER mailman
 
-You would also need the python driver `psycopg2` for Postgresql.::
+You would also need the Python driver `psycopg2` for PostgreSQL::
 
     $ pip install psycopg2
 
@@ -52,21 +52,19 @@ You would then need to set both the `class` and `url` variables in
     class: mailman.database.postgresql.PostgreSQLDatabase
     url: postgres://myuser:mypassword@mypghost/mailman
 
-That should be it.
-
 If you have any problems, you may need to delete the database and re-create
 it::
 
     $ sudo -u postgres dropdb mailman
     $ sudo -u postgres createdb -O myuser mailman
 
-My thanks to Stephen A. Goss for his contribution of PostgreSQL support.
+Many thanks to Stephen A. Goss for his contribution of PostgreSQL support.
 
 
 MySQL
 =====
 
-First, you need to configure MySQL itself.  Lets say you create the `mailman`
+First you need to configure MySQL itself.  Lets say you create the `mailman`
 database in MySQL via::
 
     mysql> CREATE DATABASE mailman;
@@ -109,8 +107,8 @@ Mailman into that, and then run the ``alembic`` command.  For example::
       "<migration_name>"
     $ deactivate
 
-This would create a new migration which would automatically be migrated to the
-database on the next run of Mailman.
+This would create a new migration which would be applied to the database
+automatically on the next run of Mailman.
 
 People upgrading Mailman from previous versions need not do anything manually,
 as soon as a new migration is added in the sources, it will be automatically
diff --git a/src/mailman/docs/ArchiveUIin5.rst b/src/mailman/docs/hyperkitty.rst
index d4b24c92c..d56031fa9 100644
--- a/src/mailman/docs/ArchiveUIin5.rst
+++ b/src/mailman/docs/hyperkitty.rst
@@ -1,6 +1,6 @@
-=====================================
-Set up the archive ui in five minutes
-=====================================
+===================================
+ Set up HyperKitty in five minutes
+===================================
 
 .. note::
    This document is way out of date.  If you have access to the Web,
@@ -9,7 +9,7 @@ Set up the archive ui in five minutes
    `FedoraHosted`_.  If you must work offline, this document may be of some
    use, but be careful.
 
-The `hyperkitty`_ application aims at providing an interface to visualize and
+The `HyperKitty`_ application aims at providing an interface to visualize and
 explore Mailman archives.
 
 This is a `Django`_ project.
@@ -18,18 +18,18 @@ Requirements
 ============
 
 - A mail archive in `maildir format`_ (no, you don't need a running Mailman
-  3!)  Eventually hyperkitty will support `mbox format`_ for backward
+  3!)  Eventually HyperKitty will support `mbox format`_ for backward
   compatibility with *Pipermail*, and *zipped maildirs* seem like a good idea
   to save space.  **Beware:** Although you'd think that we would be able to
   manipulate the venerable *mbox* format safely and efficiently, that doesn't
   seem to be the case.  *Maildir* archives are **strongly** preferred, because
-  they are more robust to program bugs (whether in Mailman, hyperkitty, or in
+  they are more robust to program bugs (whether in Mailman, HyperKitty, or in
   the originating MUA!)
 - Django is the web framework that supports the UI.
 - `bunch`_ DOES WHAT?
 - The `notmuch mail indexer`_ is used to generate indexes (and requires
   `Xapian`_).
-- hyperkitty itself, which is a UI, and not responsible for maintaining the
+- HyperKitty itself, which is a UI, and not responsible for maintaining the
   message archive itself.  (Since the archive is in `maildir format`_, any
   modern MTA or MDA can build one for you.)
 
@@ -73,14 +73,14 @@ omit the preceding steps.  Continue with these steps.
 
     % ln -s /usr/lib/python2.7/site-packages/notmuch-0.11-py2.7.egg-info .
 
-- Install the hyperkitty sources::
+- Install the HyperKitty sources::
 
     % git clone https://github.com/hyperkitty/kittystore.git
     % git clone https://github.com/hyperkitty/hyperkitty.git
     % git clone https://github.com/hyperkitty/hyperkitty_standalone.git
 
 
-Running hyperkitty
+Running HyperKitty
 ------------------
 
 - Start it::
@@ -98,7 +98,7 @@ Running hyperkitty
 
 .. _`Development Setup Guide`: https://fedorahosted.org/hyperkitty/wiki/DevelopmentSetupGuide
 .. _`FedoraHosted`: https://fedorahosted.org/
-.. _`hyperkitty`: https://fedorahosted.org/hyperkitty/
+.. _`HyperKitty`: https://fedorahosted.org/hyperkitty/
 .. _`Django`: http://djangoproject.org/
 .. _`notmuch mail indexer`: http://notmuchmail.org
 .. _`bunch`: http://pypi.python.org/pypi/bunch
diff --git a/src/mailman/docs/install.rst b/src/mailman/docs/install.rst
new file mode 100644
index 000000000..227fc087c
--- /dev/null
+++ b/src/mailman/docs/install.rst
@@ -0,0 +1,105 @@
+======================
+ Installing Mailman 3
+======================
+
+Copyright (C) 2008-2017 by the Free Software Foundation, Inc.
+
+
+Requirements
+============
+
+For the Core, Python 3.4 or newer is required.  It can either be the default
+'python3' on your ``$PATH`` or it can be accessible via the ``python3.4``,
+``python3.5``, or ``python3.6`` binary.  If your operating system does not
+include Python 3, see http://www.python.org for information about downloading
+installers (where available) and installing it from source (when necessary or
+preferred).  Python 2 is not supported by the Core.
+
+You may need some additional dependencies, which are either available from
+your OS vendor, or can be downloaded automatically from the `Python
+Cheeseshop`_.
+
+
+Documentation
+=============
+
+The documentation for Mailman 3 is distributed throughout the sources.  The
+core documentation (such as this file) is found in the ``src/mailman/docs``
+directory, but much of the documentation is in module-specific places.  Online
+versions of the `Mailman 3 Core documentation`_ is available online.
+
+Also helpful might be Mark Sapiro's documentation on `building out the
+mailman3.org`_ server.
+
+
+Get the sources
+===============
+
+The Mailman 3 source code is version controlled using Git. You can get a
+local copy by running this command::
+
+    $ git clone https://gitlab.com/mailman/mailman.git
+
+or if you have a GitLab account and prefer ssh::
+
+    $ git clone git@gitlab.com:mailman/mailman.git
+
+
+Running Mailman 3
+=================
+
+You will need to set up a configuration file to override the defaults and set
+things up for your environment.  Mailman is configured using an "ini"-style
+configuration system.  Usually this means creating a ``mailman.cfg`` file and
+putting it in a standard search location.  See the :ref:`configuration
+<configuration>` documentation for details.
+
+By default, all runtime files are put under a ``var`` directory in the current
+working directory.
+
+Run the ``mailman info`` command to see which configuration file Mailman is
+using, and where it will put its database file.  The first time you run this,
+Mailman will also create any necessary run-time directories and log files.
+
+Try ``mailman --help`` for more details.  You can use the commands
+``mailman start`` to start the runner subprocess daemons, and of course
+``mailman stop`` to stop them.
+
+Note that you can also run Mailman from one of the virtual environments
+created by tox, e.g.::
+
+    $ tox -e py35-nocov --notest -r
+    $ .tox/py35-nocov/bin/mailman info
+
+
+Mailman Shell
+=============
+
+This documentation has examples which use the Mailman shell to interact with
+Mailman.  To start the shell type ``mailman shell`` in your terminal.
+
+There are some testings functions which need to be imported first before you
+use them.  They can be imported from the modules available in
+``mailman.testing``.  For example, to use ``dump_list`` you first need to
+import it from the ``mailman.testing.documentation`` module.
+
+.. Of course, *this* doctest doesn't have these preloaded...
+   >>> from zope.component import getUtility
+   >>> from mailman.interfaces.listmanager import IListManager
+
+The shell automatically initializes the Mailman system, loads all the
+available interfaces, and configures the `Zope Component Architecture`_ (ZCA)
+which is used to access all the software components in Mailman.  So for
+example, if you wanted to get access to the list manager component, you could
+do::
+
+    $ mailman shell
+    Welcome to the GNU Mailman shell
+
+    >>> list_manager = getUtility(IListManager)
+
+
+.. _`Python Cheeseshop`: http://pypi.python.org/pypi
+.. _`Mailman 3 Core documentation`: https://mailman.readthedocs.io
+.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
+.. _`building out the mailman3.org`: https://wiki.list.org/DOC/Mailman%203%20installation%20experience
diff --git a/src/mailman/docs/INTRODUCTION.rst b/src/mailman/docs/introduction.rst
index b058c3193..9814796cd 100644
--- a/src/mailman/docs/INTRODUCTION.rst
+++ b/src/mailman/docs/introduction.rst
@@ -1,3 +1,5 @@
+.. _start-here:
+
 ================================================
 Mailman - The GNU Mailing List Management System
 ================================================
@@ -19,13 +21,12 @@ GNU Mailman 3 consists of a `suite of programs`_ that work together:
 * HyperKitty; the web-based archiver
 * Mailman client; the official Python bindings for talking to the Core's REST
   administrative API.
-* Mailman bundler; a convenient way to deploy Mailman 3.
 
-Only the Core is required.  You could easily write your own web user interface
-or archiver that speaks to the Core over its REST API.  The REST API is a pure
-HTTP-based API so you don't *have* to use Python, or even our official
-bindings.  And you can deploy whatever components you want using whatever
-mechanisms you want.
+Only the Core is required.  You can write or integrate your own web user
+interface or archiver that speaks to the Core over its REST API.  The REST API
+is a pure HTTP-based API so you don't *have* to use Python, or even our
+official bindings.  And you can deploy whatever components you want using
+whatever mechanisms you want.
 
 But we really like Postorius and HyperKitty and hope you will too!
 
@@ -65,39 +66,25 @@ Mailman was originally developed by John Viega in the mid-1990s.  Subsequent
 development (through version 1.0b3) was by Ken Manheimer.  Further work
 towards the 1.0 final release was a group effort, with the core contributors
 being: Barry Warsaw, Ken Manheimer, Scott Cotton, Harald Meland, and John
-Viega.  Version 1.0 and beyond have been primarily maintained by Barry Warsaw
-with contributions from many; see the `ACKNOWLEDGMENTS`_ file for details.
-Jeremy Hylton helped considerably with the Pipermail code in Mailman 2.0.
-Mailman 2.1 is primarily maintained by Mark Sapiro, with previous help by
-Tokio Kikuchi.  Barry Warsaw is the lead developer on Mailman 3.  Aurélien
+Viega.  Since version 1.0 the project has been led by Barry Warsaw with
+contributions from many; see the `ACKNOWLEDGMENTS`_ file for details.  Jeremy
+Hylton helped considerably with the Pipermail code in Mailman 2.0.  Mailman
+2.1 is primarily maintained by Mark Sapiro, with previous help by Tokio
+Kikuchi (RIP).  Barry Warsaw is the lead developer on Mailman 3.  Aurélien
 Bompard and Florian Fuchs lead development of Postorius and HyperKitty.
-Abhilash Raj is a valued contributor to all bits and maintains the CI
-infrastructure.
+Abhilash Raj is a core developer contributing to all the bits and maintains
+the CI infrastructure.
 
 
 Project details
 ===============
 
-The Mailman home page is:
-
-* http://www.list.org
-
-The community driven wiki (including the FAQ_) is at:
-
-* http://wiki.list.org
-
-Other help resources, such as on-line documentation, links to the mailing
-lists and archives, etc., are available at:
-
-* http://www.list.org/help.html
-
-Mailman 3 is maintained on GitLab:
-
-* https://gitlab.com/groups/mailman
-
-You can report issues in the Core at:
-
-* https://gitlab.com/mailman/mailman/issues
+* Project home page: http://www.list.org
+* Documentation: https: https://mailman.readthedocs.io
+* The community driven wiki (including the FAQ_): https://wiki.list.org
+* Additional help resources: http://www.list.org/help.html
+* Report Core bugs at: https://gitlab.com/mailman/mailman/issues
+* Mailman 3 suite on GitLab: https://gitlab.com/groups/mailman
 
 (GNU Mailman 2.1 is still maintained on Launchpad_.)
 
diff --git a/src/mailman/docs/MTA.rst b/src/mailman/docs/mta.rst
index ac38c3026..2a7f3d6d9 100644
--- a/src/mailman/docs/MTA.rst
+++ b/src/mailman/docs/mta.rst
@@ -1,6 +1,6 @@
-===========================
-Hooking up your mail server
-===========================
+=============================
+ Hooking up your mail server
+=============================
 
 Mailman needs to communicate with your *MTA* (*mail transport agent*
 or *mail server*, the software which handles sending mail across the
@@ -10,12 +10,11 @@ to its immediate upstream MTA, which delivers them.  In the same way,
 Mailman never receives mail directly.  Mail from outside always comes
 via the MTA.
 
-Mailman accepts incoming messages from the MTA using the `Local Mail
-Transfer Protocol`_ (LMTP_) interface.  Mailman can use other incoming
-transports, but LMTP is much more efficient than spawning a process
-just to do the delivery.  Most open source MTAs support LMTP for local
-delivery.  If yours doesn't, and you need to use a different
-interface, please ask on the `mailing list or on IRC`_.
+Mailman accepts incoming messages from the MTA using the `Local Mail Transfer
+Protocol`_ (LMTP_) interface.  LMTP is much more efficient than spawning a
+process just to do the delivery.  Most open source MTAs support LMTP for local
+delivery.  If yours doesn't, and you need to use a different interface, please
+ask on the `mailing list or on IRC`_.
 
 Mailman passes all outgoing messages to the MTA using the `Simple Mail
 Transfer Protocol`_ (SMTP_).
@@ -50,6 +49,10 @@ and other attributes of the communication channel.  This is why some
 constraints on the format of attributes arise (e.g., ``lmtp_host``), even
 though Mailman itself has no problem with them.
 
+It is possible (although not documented here) to completely replace or
+override the default mechanisms to handle both incoming and outgoing mail.
+Mailman is highly customizable here!
+
 The ``incoming`` and ``outgoing`` parameters identify the Python objects used
 to communicate with the MTA.  The ``python:`` scheme indicates that the paths
 should be a dotted Python module specification.  The ``deliver`` module used
@@ -57,23 +60,21 @@ in ``outgoing`` should be satisfactory for most MTAs.  The ``postfix`` module
 in ``incoming`` is specific to the Postfix MTA.  See the section for your MTA
 below for details on these parameters.
 
-``lmtp_host`` and ``lmtp_port`` are parameters which are used by
-Mailman, but also will be passed to the MTA to identify the Mailman
-host.  The "same host" case is special; some MTAs (including Postfix)
-do not recognize "localhost", and need the numerical IP address.  If
-they are on different hosts, ``lmtp_host`` should be set to the domain
-name or IP address of the Mailman host.  ``lmtp_port`` is fairly
-arbitrary (there is no standard port for LMTP).  Use any port
-convenient for your site.  "8024" is as good as any, unless another
-service is using it.
+``lmtp_host`` and ``lmtp_port`` are parameters which are used by Mailman, but
+also will be passed to the MTA to identify the Mailman host.  The "same host"
+case is special; some MTAs (including Postfix) do not recognize "localhost",
+and need the numerical IP address.  If they are on different hosts,
+``lmtp_host`` should be set to the domain name or IP address of the Mailman
+host.  ``lmtp_port`` is fairly arbitrary (there is no standard port for LMTP).
+Use any port convenient for your site.  "8024" is as good as any, unless
+another service is using it.
 
-``smtp_host`` and ``smtp_port`` are parameters used to identify the
-MTA to Mailman.  If the MTA and Mailman are on separate hosts,
-``smtp_host`` should be set to the domain name or IP address of the
-MTA host.  ``smtp_port`` will almost always be 25, which is the
-standard port for SMTP.  (Some special site configurations set it to a
-different port.  If you need this, you probably already know that,
-know why, and what to do, too!)
+``smtp_host`` and ``smtp_port`` are parameters used to identify the MTA to
+Mailman.  If the MTA and Mailman are on separate hosts, ``smtp_host`` should
+be set to the domain name or IP address of the MTA host.  ``smtp_port`` will
+almost always be 25, which is the standard port for SMTP.  (Some special site
+configurations set it to a different port.  If you need this, you probably
+already know that, know why, and what to do, too!)
 
 Mailman also provides many other configuration variables that you can
 use to tweak performance for your operating environment.  See the
@@ -317,9 +318,9 @@ Mostly defaults in mailman.cfg::
     # changed if there is a conflict with other software using that port.
     lmtp_port: 8024
 
-This will listen on localhost:8024 with LMTP and deliver outgoing
-messages to localhost:25.  See ``mailman/config/schema.cfg`` for more
-information on these settings.
+This will listen on ``localhost:8024`` with LMTP and deliver outgoing messages
+to ``localhost:25``.  See ``mailman/config/schema.cfg`` for more information
+on these settings.
 
 qmail configuration
 -------------------
diff --git a/src/mailman/docs/WebUIin5.rst b/src/mailman/docs/postorius.rst
index 70716e6a7..f1cc2b96e 100644
--- a/src/mailman/docs/WebUIin5.rst
+++ b/src/mailman/docs/postorius.rst
@@ -1,27 +1,27 @@
-================================
-Set up Postorius in five minutes
-================================
+==================================
+ Set up Postorius in five minutes
+==================================
 
 This is a quick guide for setting up a development environment to work on
 Mailman 3's web UI, called Postorius.  If all goes as planned, you should be
 done within 5 minutes.  This has been tested on Ubuntu 11.04.
 
 In order to download the components necessary you need to have the `Git`_
-version control system installed on your system.  Mailman requires Python 3.4,
-while mailman.client needs at least Python version 2.6.
+version control system installed on your system.  Mailman requires Python 3.4
+or newer, while mailman.client needs at least Python version 2.6.
 
 It's probably a good idea to set up a virtual Python environment using
 `virtualenv`_.  `Here is a brief HOWTO`_.  You would need two separate virtual
 environment one using Python version 2.6 or 2.7 (for Postorius and
-mailman.client) and other using Python version 3.4 (for Mailman core).
+mailman.client) and other using Python 3 (for Mailman core).
 
 .. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
 .. _`Here is a brief HOWTO`: ./ArchiveUIin5.html#get-it-running-under-virtualenv
 .. _`Git`: http://git-scm.com
 
 
-GNU Mailman 3
-=============
+Mailman Core
+============
 
 First download the latest revision of Mailman 3 from Gitlab.
 ::
@@ -81,21 +81,3 @@ a project already developed which you can set up like this::
   $(py2) python manage.py runserver
 
 The last command will start the dev server on http://localhost:8000.
-
-
-A note for MacOS X users (and possibly others running python 2.7)
-=================================================================
-
-*Note: These paragraphs are struck-through on the Mailman wiki.*
-
-On an OS X 10.7 (Lion) system, some of these steps needed to be modified to
-use python2.6 instead of python. (In particular, bzr is known to behave badly
-when used python2.7 on OS X 10.7 at the moment -- hopefully this will be fixed
-and no longer an issue soon.)
-
-You will need to install the latest version of XCode on MacOS 10.7, which is
-available for free from the App Store.  If you had a previous version of XCode
-installed when you upgraded to 10.7, it will no longer work and will not have
-automatically been upgraded, so be prepared to install again.  Once you have
-it installed from the App Store, you will still need to go run the installer
-from ``/Applications`` to complete the installation.
diff --git a/src/mailman/docs/RELEASENOTES.rst b/src/mailman/docs/release-notes.rst
index 00d29bb7e..bccb03bf8 100644
--- a/src/mailman/docs/RELEASENOTES.rst
+++ b/src/mailman/docs/release-notes.rst
@@ -19,8 +19,7 @@ Mailman 3 may have bugs.
 Mailman 3 is not yet feature complete with Mailman 2.1.
 
 The documentation here describes the Mailman Core in great detail.  Postorius,
-Hyperkitty, mailman.client, and the bundler are described and developed
-elsewhere.
+Hyperkitty, and mailman.client are described and developed elsewhere.
 
 More release notes are maintained on the `Mailman wiki`_.
 
diff --git a/src/mailman/rest/docs/basic.rst b/src/mailman/rest/docs/basic.rst
index 45ace87ec..e1a712980 100644
--- a/src/mailman/rest/docs/basic.rst
+++ b/src/mailman/rest/docs/basic.rst
@@ -1,21 +1,9 @@
-===========
-REST server
-===========
-
-Mailman exposes a REST HTTP server for administrative control.
-
-The server listens for connections on a configurable host name and port.
+=================
+ Basic operation
+=================
 
-It is always protected by HTTP basic authentication using a single global
-user name and password. The credentials are set in the `[webservice]` section
-of the configuration using the `admin_user` and `admin_pass` properties.
-
-Because the REST server has full administrative access, it should always be
-run only on localhost, unless you really know what you're doing.  In addition
-you should set the user name and password to secure values and distribute them
-to any REST clients with reasonable precautions.
-
-The Mailman major and minor version numbers are in the URL.
+In order to do anything with the REST API, you need to know its `Basic AUTH`_
+credentials, and the version of the API you wish to speak to.
 
 
 Credentials
@@ -35,8 +23,8 @@ succeeds.
     200
 
 
-Version information
-===================
+System version information
+==========================
 
 System version information can be retrieved from the server, in the form of a
 JSON encoded response.
@@ -49,4 +37,30 @@ JSON encoded response.
     self_link: http://localhost:9001/3.0/system/versions
 
 
+API Versions
+============
+
+The REST API exposes two versions which are almost completely identical.  As
+you've seen above, the ``3.0`` API is the base API.  There is also a ``3.1``
+API, which can be used interchangably::
+
+    >>> dump_json('http://localhost:9001/3.1/system/versions')
+    api_version: 3.1
+    http_etag: "..."
+    mailman_version: GNU Mailman 3...
+    python_version: ...
+    self_link: http://localhost:9001/3.1/system/versions
+
+The only difference is the way UUIDs are represented.  UUIDs are 128-bit
+unique ids for objects such as users and members.  In version ``3.0`` of the
+API, UUIDs are represented as 128-bit integers, but these were found to be
+incompatible for some versions of JavaScript, so in API version ``3.1`` UUIDs
+are represented as hex strings.
+
+Choose whichever API version makes sense for your application.  In general, we
+recommend using API ``3.1``, but most of the current documentation describes
+API ``3.0``.  Just make the mental substitution as you read along.
+
+
 .. _REST: http://en.wikipedia.org/wiki/REST
+.. _`Basic AUTH`: https://en.wikipedia.org/wiki/Basic_auth
diff --git a/src/mailman/rest/docs/rest.rst b/src/mailman/rest/docs/rest.rst
index 8461e641d..ca962ad61 100644
--- a/src/mailman/rest/docs/rest.rst
+++ b/src/mailman/rest/docs/rest.rst
@@ -1,8 +1,51 @@
-========
-REST API
-========
+.. _rest-api:
+
+========================================
+ Mailman 3 Core administrative REST API
+========================================
+
+Here is extensive documentation on the Mailman Core administrative REST API.
+
+
+The REST server
+===============
+
+Mailman exposes a REST HTTP server for administrative control.
+
+The server listens for connections on a configurable host name and port.
+
+It is always protected by HTTP basic authentication using a single global
+user name and password. The credentials are set in the `[webservice]` section
+of the configuration using the `admin_user` and `admin_pass` properties.
+
+Because the REST server has full administrative access, it should never be
+exposed to the public internet.  By default it only listens to connections on
+``localhost``.  Don't change this unless you really know what you're doing.
+In addition you should set the user name and password to secure values and
+distribute them to any REST clients with reasonable precautions.
+
+The Mailman major and minor version numbers are in the URL.
+
+You can write your own HTTP clients to speak this API, or you can use the
+`official Python bindings`_.
+
 
 .. toctree::
    :glob:
+   :maxdepth: 1
 
+   ./basic
+   ./collections
+   ./helpers
+   ./systemconf
+   ./domains
+   ./lists
+   ./listconf
+   ./addresses
+   ./users
+   ./membership
+   ./queues
    ./*
+
+
+.. _`official Python bindings`: https://mailmanclient.readthedocs.io/en/latest/