Hi,

I am Aditi and I work as a Software Development Engineer at HackerRank. I worked with GNU Mailman and Systers in GSoC'16 and GSoC'17. And am interested in working with GNU Mailman for the Google Season of Docs'19.

Thank you Steve for mentioning all the responsibilities and the expectations from the technical writer. It will be really helpful to get started. Also, It would be helpful if you can tell us what is expected in the proposal. Looking forward to working with you and Abhilash again :)

Thanks and Regards, Aditi ᐧ

On Fri, May 31, 2019 at 12:53 PM Stephen J. Turnbull < turnbull.stephen.fw@u.tsukuba.ac.jp> wrote:

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 Mailman-Users@mailman3.org (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: turnbull@sk.tsukuba.ac.jp University of Tsukuba Tel: 029-853-5175 Tennodai 1-1-1, Tsukuba 305-8573 JAPAN

---

Mailman-Developers mailing list -- mailman-developers@python.org To unsubscribe send an email to mailman-developers-leave@python.org 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

Hi Season of Docs peeps!

I have updated the GSoD page as promised. If you read the referenced posts, there won't be anything new to you, but it may be organized a bit better.

Aspiring tech writers should apply to Google now, and specify GNU Mailman as your desired organization. You may apply more than once (I don't know if there's a limit, it's 5 in GSoC) to more than one organization. There's a little bit of information and a link to the GSoD site here: https://wiki.list.org/DEV/SeasonOfDocs2019#GSoD_Application_Process.

If GSoD uses a process similar to GSoC's, the proposal itself will be created as a Google doc.

I'm not sure how much structure the GSoD application form provides. Here's a basic outline of what we want to see. I'll try to refine it over the next couple of days, and post it to the GSoD page on our wiki.

At the top:

1. Contact information: your name (GSoD rules imply this may be a pseudonym; I have no problem with that and I'll check with Abhilash -- note that to get paid you have to give Google a real name, though!), email, phone number, IRC handle, any SNS handles you want to provide. This is most readable in "mail header format":

   Name: .... E-mail: .... Phone: +(country code) (phone number) etc.

2. Three or four line summary of what task you propose to address.

Following, in some order, but not necessarily as written below:

3. Three or four lines of personal PR, something special about you that makes you a great choice for this program.

4. A resume of any work you've done as a writer or with an open source software project. It doesn't need to be formal. If it's publicly accessible, provide URLs. It doesn't need to be very long (and probably shouldn't be: at most four examples most representative of your best work).

5. A description of the work you propose to do. Write this well! Keep it at a consistent level of detail as much as possible.

6. A schedule for the work. Most important is to note any times you know you will be unavailable to work or off-line and hard to contact.

   The schedule should specify milestones. Milestones are a crucial component of any schedule because they allow you to know whether you are keeping up with the schedule or not.

   A *milestone* may be a deliverable such as a merge request for a document, or it may be some recognizable state along with an *objective* criterion for completion. For a 14-week project, 10-12 milestones is probably a good target. Less is acceptable, more is certainly overkill.

   Don't be afraid of the milestones. Setting good milestones and estimating time to completion is a difficult art. You get better at it with practice. We don't expect everyone to write good milestones or to keep them with metronome precision, and we'll help you with writing yours. But avoiding them is a bad sign. It says your attitude is "I'll deliver when I deliver, you can just wait." And just thinking about them is useful. It requires rough estimates of the quantity of work and time required, and that will reflect on the proposal itself.

Looking forward to seeing everyone's proposals!

Steve

Abhilash Raj writes:

On Fri, May 31, 2019, at 12:24 AM, Stephen J. Turnbull wrote:

...

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.