Hi,
I'm Steve, the org admin and principal mentor for Season of Docs
(GSoD). The other mentor, Abhilash, is also Mailman project lead and
org admin for Season of Code (GSoC). To pile on to those
responsibilities, most of Mailman core (including all currently active
devs) was at PyCon April 30 to May 9, work has sprung a few unpleasant
surprises, and well, here we are.
I will try to update our SoD page on the wiki "soon" (probably Sunday),
and will announce that when it happens here. In the meantime,
1. Mailman has always considered docs important, and we try to write
our documentation at the same time as writing the code. This has
good and bad effects on the quality of documentation, but for
GSoD, it means you have to have a local git repo of the Mailman
suite, because the docs are physically intermingled with code and
tests. The code is at https://gitlab.com/mailman. If you need
help with git, ssh, and/or gitlab (you need a gitlab account with
at least one ssh public key installed), let us know.
We require at least one merged MR of the qualifying tech writer.
That MR can be a typo fix. The point of it is simply to show that
you know how to get an MR through the Mailman development
process.
2. You DO NOT need to build and have a working Mailman installation
locally. It can help if you do, but we do not require it of tech
writers (and I'm pretty sure GSoD has a rule against that). We'll
do something about providing a working installation that you can
log into and see all the screens and options.
The build system for the docs is separate from the build and
install system for Mailman code and data. You do need to be able
to build the documentation yourself. This means having Python 3
and Sphinx installed. Python 3.6 is the latest version mentioned
on the front page of the docs site, but I believe Python 3.7 is
actually supported, and Python 3.8 is now in beta. So I would
recommend installing Python 3.7 unless you have Python 3.6 already
installed and are space-poor. (If *and only if* you do a lot of
development in Python, sure, you could install Python 3.8 beat.
Any Mailman testing you can do with bleeding edge Python is always
welcome :-) but don't let it get in the way of working on docs! ;-)
3. The current documentation is visible at
https://mailman.readthedocs.io/, which should redirect to
https://mailman.readthedocs.io/en/latest/. (If it doesn't
redirect there, please let us know. Tasks you can start thinking
about (and creating MRs = merge requests for) immediately:
a. The documents are written in a dialect of RestructuredText
used with the Sphinx document production system. Learn about
these.
b. Subscribe to [email protected] (the Postorius
interface is at https://lists.mailman3.org/). Browse the
various pages, and write down questions about them (even if
you already know the answers). Then go to
mailman.readthedocs.io and see if you can find those answers.
If not, you know what to do. :-)
c. The structure of the documentation needs to be redesigned.
Most of the important stuff is linked, and linked early, from
the front page, which is good. That's the nicest thing I can
say about it. :-( Here's a sketch of what we might do about it:
It's conventional in open source projects to start with a
section explaining how to install: hardware and software
requirements, building the software if needed, installing it,
configuring it, configuring other software (specifically DNS
and MTA) to work with Mailman, creating domains, lists, and
users, and starting the whole shebang running. I'm open to
other organizations, but this is a very plausible first
"chapter".
One thing we don't have is subscriber documentation. Yes, we
have documentation on subscriber interactions with Postorius
and HyperKitty. What I'm talking about here are the "Easter
eggs" in mailing list mail, to help users organize their
mailing lists and use them effectively. For example, it's
easy with most mail clients to filter on the "List-Id" header
field, and this is most reliable. Many lists provide
unsubscription and options links in the footer. There's
usually a header field providing the archive URL to that post,
and sometimes a link in the footer.
Next would be a section for subscribers on managing your
Mailman user, emails, and subscriptions, including the options
available for each. I think this would probably document both
Postorius and HyperKitty. (As I implied above, this structure
is a conversation starter, not a plan I've thought carefully
about.)
Then a section for admins, list admins (owners and moderators)
first, then domain admins, then site admins.
Then a section on troubleshooting for admins.
Then a section for devs (there's a lot of dev material linked
directly from the top page, which I don't think is
appropriate).
Finally a section for miscellaneous stuff we don't know what
else to do with.
d. The content of the front page is somewhat eclectic, not to say
"disorganized". Rewriting that page, and then "chapter" front
pages are early goals.
In the case of improving structure (part c, above), it's OK to
work alone, submit MRs, get them merged. Structure is very
visible in the sidebar and menus of links. If somebody has a
different idea, they'll say so, present a new MR, and we can
discuss.
Don't do that with page content. Announce you're working on a
particular section, with a URL to an MR, early. *Explicitly
ask for review.* Gitlab has a feature (ask us how it works)
that allows the MR to track your local work: it's as dynamic
as the branch you are committing to. I'm pretty sure it even
allows an automatic "squash" at merge time if you think that
makes the history look nicer. Once you have edit permissions
on Gitlab, you'll get an "edit on Gitlab" button on the page.
It's OK to use it for typos and other change that affect only
one line, but avoid the temptation to do full-page rewrites
that way. Create a merge request and try to encourage
discussion.
The reason for this is that you're not writing a novel. A
consistent style throughout the documentation is more
important than an interesting style. Discussing with other
people has three effects here: some of their suggestions are
just plain better, maybe you'll change your mind and move
towards someone else's style just for group harmony, and maybe
they'll harmonize with you (even though they're not directly
writing this section, if their style in *other* sections is
more like yours, the reader benefits).
Note that "style" here includes things like the wording and
placement of link anchors. Readers often go right by the link
you put there because the wording or position on the page
isn't quite what they expect. You can't do much about that
the first time, but if style is consistent, they will learn
it.
Wouldn't the commit-then-adjust process work here as well as
for structure? That's debatable, but my feeling is no. There
are two problems. First, a full page rewritten by a single
author will have a coherent style, even if that style is
inconsistent with other pages. Unless it's really different,
it's harder to notice inconsistency between pages than it is
to see inconsistency within a page. Second, there's a strong
tendency for developers (including tech writers) to think "oh,
there's a commit, it passed the CI tests, good!" and not
review it, both because it costs personal energy to review,
and to avoid interpersonal conflict after a commit. It's much
easier to "bikeshed" minor changes *before* they get promoted
to the public repository. And, of course, as I mentioned
above, discussion itself is an important vehicle for
harmonizing style.
I think that will do for now.
Thanks to Ayush and others who brought this up.
Steve
--
Associate Professor Division of Policy and Planning Science
http://turnbull.sk.tsukuba.ac.jp/ Faculty of Systems and Information
Email: [email protected] University of Tsukuba
Tel: 029-853-5175 Tennodai 1-1-1, Tsukuba 305-8573 JAPAN
_______________________________________________
Mailman-Developers mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/mailman-developers.python.org/
Mailman FAQ: https://wiki.list.org/x/AgA3
Security Policy: https://wiki.list.org/x/QIA9
