MailmanWiki

Google Season of Docs 2019 Ideas Page

Mailman is free software for managing electronic mail discussion and e-newsletter lists. Mailman is integrated with the web, making it easy for users to manage their accounts and for list owners to administer their lists. Mailman supports built-in archiving, automatic bounce processing, content filtering, digest delivery, spam filters, and more. Many open source denizens will be familiar with Mailman 2.1, which is used to manage many project mailing lists. All of our current work is on Mailman 3, which was released in 2015, but there's still lots of room for new features and ideas!

Are you just here for our GSoD Proposal Template? <-- Look no further!

Not sure about how GSoD works? Check out the GSoD home page

Aren't familiar with Mailman, the project? We're a friendly, open organization committed to diversity. We subscribe to the Python Code of Conduct. We cooperate on and off with other organizations, most frequently Systers and the Python Software Foundation. Google Season of Docs is a brand new program, so we have no experience with it, but Mailman has been accepted to Google Summer of Code (GSoC) every year from 2012 to 2019 (sometimes under the Python Software Foundation umbrella, mostly as an independent organization), except 2018 when we decided to take a break. Our organization admins Steve and Abhilash are both experienced GSoC mentors, and we have several other experienced mentors who have not yet been able to commit to Season of Docs as "official" mentors, but certainly will chip in to help as they can. Our students have generally been successful in other orgs as well, and Abhilash himself was originally recruited to Mailman as a GSoC intern in 2013.

Contents

  1. Google Season of Docs 2019 Ideas Page
    1. Getting Started
    2. Recommended Skills
    3. What is Mailman Suite?
    4. GSoD Application Process
    5. Contacting us
    6. Minimal Qualification Tasks
    7. Writing Your Proposal
    8. About Working on the Mailman Suite Documentation
    9. Project Ideas
      1. Instructions for Migrating from Mailman 2 to Mailman 3
        1. Additional Requirements
        2. Mentors
      2. Developers' Documentation for Hyperkitty
        1. Additional Requirements
        2. Mentors
      3. Developers' Documentation for Postorius
        1. Additional Requirements
        2. Mentors
      4. Documentation Structure
        1. Additional Requirements
        2. Mentors
      5. Landing Pages
        1. Additional Requirements
        2. Mentors
    10. FAQ
    11. Documentation & Installation

Getting Started

The GSoD getting started page has some great general GSoD information. Read it first!

Before you ask any questions about how to do anything in git or initialize your repository please read through the git howto and see if that answers your questions.

Here's a few skills that will make it easier for you to get started as a Mailman technical writer. The only essential:

Optional but very helpful (in order of importance):

Specific projects may have additional desired skills listed along with them.

What is Mailman Suite?

The previous version, Mailman 2 (like many other mailing list managers) is a single project, tightly integrated. In Mailman 3, we've divided up the code into a number of sub-projects, with the intent of providing a full working site, but also allowing sites to set up their own "dashboards" and archiving systems. We refer to the whole package as "Mailman Suite" and there's a few really important pieces you should know:

There's also a number of smaller projects that provide the glue to make these pieces work well together, or allow them to be used separately.

All the Mailman source is now on GitLab.

GSoD Application Process

To start, write to Mailman Developers <mailman-developers@python.org>, and tell us you're interested in working on the Mailman documentation for Google Season of Docs. We'll help you create a documentation proposal, and refine it. Don't forget to subscribe to the list at https://mail.python.org/mailman3/lists/mailman-developers.python.org/.

Once the application period starts on May 29, you should make a formal application on the Google Season of Docs site. The application form is available in the technical writer guide during the technical writer application phase. This information will be the information that we see for evaluation, plus your activity on our channels, and perhaps some personal interaction on private channels.

After submitting the form, you can continue updating the information on the form until the end of the technical writer application phase on June 28.

We haven't seen the form that GSoD forwards to us yet. We will be providing a format for the proposal itself shortly. This may require additional information over and above that requested by Google.

Contacting us

The most successful GSoD students are the ones who work closely with the Mailman team. As you might expect from a group that makes mailing list software, our preferred method of communication is our mailing list, but we also have an IRC channel. Please do not send private messages or emails unless asked to do so or the subject is personal rather than technical, since we get a lot of similar questions and would rather the questions and answers happen in public so everyone can benefit.

We expect that everybody will be comfortable with communicating by email, but of course sometimes you want something a little more interactive. Since IRC is a little geeky, we'll seriously consider alternative messaging apps. (No promises, except to consider.)

Minimal Qualification Tasks

You must have a local git repo of the Mailman suite. 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.

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.

Learn about RestructuredText and Sphinx. The documents are written in a dialect of RestructuredText used with the Sphinx document production system.

You do need to be able to build the documentation yourself. The build system for the docs is separate from the build and install system for Mailman code and data. 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 beta. 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! ;-)

Become familiar with the current documentation. It is visible at http://docs.mailman3.org/en/latest/. (In case you've been there, https://mailman.readthedocs.io/, which redirects to https://mailman.readthedocs.io/en/latest/, is just the documentation for Mailman 3 core, the database and mail distribution component.)

Subscribe to Mailman Users (for Mailman 3). Go to https://lists.mailman3.org/mailman3/lists/. This is a fairly low-traffic list so far, so it shouldn't be burdensome. While you're there, browse the various pages for the Mailman, and write down questions about them (even if you already know the answers!) Then go to docs.mailman3.org and see if you can find those answers. If you don't, write them. :-)

Writing Your Proposal

This page is still under development, but here are some references that our Summer of Code interns have found useful.

About Working on the Mailman Suite Documentation

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. The main way it affects you is that, for the convenience of the developers who author most of the documentation, the documentation is mixed in with the code.

One task described below is improving the structure (organization) of the documentation. In this case, 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 on Mailman Developers that 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. There's no extra work for updating your merge request, so there's no reason not to post it early. I'm pretty sure Gitlab 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 these rules about page content is that you're not writing a novel, where your personal style is the sales point. 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.

Project Ideas

If you have other idea you'd like to propose , please send it to mailman-developers@python.org for discussion! You can also look at the to-do list for Mailman 3.0 here, and see if anything is interesting enough that you would like to work on it through the summer.

Instructions for Migrating from Mailman 2 to Mailman 3

Our biggest lack in documentation is a comprehensive guide for existing Mailman 2 users who wish to switch to Mailman 3. We have some "how to" style guides, but questions on the mailing lists indicate that they're insufficient, with many details that users have to cover.

Additional Requirements

Mentors

Developers' Documentation for Hyperkitty

Hyperkitty is GNU Mailman's official archiver. However, it also supports some advanced functionality which allows users to send messages/emails through its web interface.

HyperKitty was developed with support from Red Hat. As the application matured and the company's needs changed, the original developers were reassigned. Documentation at the function level (docstrings and comments) is pretty good. However, documentation of the configuration and architecture of the application is almost nonexistent, and would be very helpful in onboarding developers who want to work on this subproject.

Additional Requirements

Mentors

Developers' Documentation for Postorius

Postorius is GNU Mailman's bundled "dashboard" for mailing list administrators and subscribers.

The main developers of Postorius have become less attached to the project. The documentation has become out of date over time. Improved documentation of the configuration and architecture of the application would be very helpful in onboarding developers who want to work on this subproject.

Additional Requirements

Mentors

Documentation Structure

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" because most of our clients are site owners, followed by a few list owners. Subscriber questions are pretty rare.

We don't have subscriber documentation on using mailing lists. Yes, we have documentation on subscriber interactions with Postorius to configure their mailing lists and with HyperKitty to browse the archives. 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 on mailman.readthedocs.io, which I'm not sure is appropriate).

Finally a section for miscellaneous stuff we don't know what else to do with.

Additional Requirements

Mentors

Landing Pages

The content of the front page is somewhat "eclectic". Rewriting that page, and then "chapter" front pages are important tasks.

Additional Requirements

Mentors

FAQ

This FAQ is a placeholder ripped off from our GSoC page. Check back later to see if it's more useful for tech writers!

This page might be of some help.

This question has been asked tons of times on the mailing list (mentioned above) and IRC Channel (again, mentioned above). Both of them are logged publicly and are searchable. It would be really nice to go through them once before you ask the same question again. More specific questions are encouraged and receive more attention than "How do I start?". Mentors do try hard to reply to each and every email to the developers list, but in case you don't get any replies on trivial questions, don't be discouraged. Also, in case you are a student, helping others with small problems that you know about is also a great way to get noticed. Don't worry too much about giving wrong answers, list is constantly monitored by the core developers and your mistakes would be corrected.

Issues, bugs and tests are obviously a good way to contribute. But, writing/improving documentation is another great way to contribute for beginners. It doesn't have to be a real commit or patch, write up a detailed blog post about what problems you faced while setting up mailman for development. What parts of mailman you find are difficult to understand? What are awesome things about mailman?

Note: To qualify for Google Summer of Code, your proposed project must be a coding project. That's Google's rule. Documentation and tests help to make a substantial contribution, but only count toward GSoC to the extent that they apply to your new or changed code. Additional work on documentation or testing is considered a community contribution, which is a consideration in deciding who to accept.

In most of the cases the reason for a MR to be pending is that there is either something missing or something incorrect. In either of those cases, first check the MR itself and any issues associated with it, to see if there are comment you have missed. If it's not obvious what you need to do next, contact any mentor or the org admin (maxking) and we'll look into it, or ask the relevant person. I don't mean that you do that for each one, just the ones that haven't been noticed by anyone for a *long time*. (Use your judgment as to what is "long" when there's a deadline coming up.)

Documentation & Installation

This section is probably not useful to technical writers. But just in case your hobby is programming, we've borrowed this from our GSoC page, too.

Here are some useful links to get you started with Mailman Development:

Mailman is written in Python. Mailman supports Python 3.5+. Each individual project may have their own restrictions on the Python versions you can use depending on the support of the their dependencies.

MailmanWiki: DEV/SeasonOfDocs2019 (last edited 2019-06-25 17:33:46 by stephen@xemacs.org)