
Hey! I am Ayush Goel, an undergraduate student at IIIT Delhi and am interested in working with GNU Mailman for the Google Season of Docs 19. Currently, I have already joined the mailing list and am setting up Mailman on my Linux machine(will reach out at the mailing list if I encounter any problem). Please guide me on how to proceed further with the application. Looking forward to hearing from you!
Yours sincerely Ayush Goel IIIT-Delhi

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,
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.
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! ;-)
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

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:

On Fri, May 31, 2019, at 12:24 AM, Stephen J. Turnbull wrote:
Slight correction to this, the above mentioned URL is the doc for Mailman Core, the "Landing Page" for all the Mailman documentation is supposed to be http://docs.mailman3.org/en/latest/.
-- thanks, Abhilash Raj (maxking)

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:
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.
Three or four line summary of what task you propose to address.
Following, in some order, but not necessarily as written below:
Three or four lines of personal PR, something special about you that makes you a great choice for this program.
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).
A description of the work you propose to do. Write this well! Keep it at a consistent level of detail as much as possible.
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:

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,
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.
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! ;-)
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

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:

On Fri, May 31, 2019, at 12:24 AM, Stephen J. Turnbull wrote:
Slight correction to this, the above mentioned URL is the doc for Mailman Core, the "Landing Page" for all the Mailman documentation is supposed to be http://docs.mailman3.org/en/latest/.
-- thanks, Abhilash Raj (maxking)

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:
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.
Three or four line summary of what task you propose to address.
Following, in some order, but not necessarily as written below:
Three or four lines of personal PR, something special about you that makes you a great choice for this program.
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).
A description of the work you propose to do. Write this well! Keep it at a consistent level of detail as much as possible.
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:
participants (4)
-
Abhilash Raj
-
ADITI GUPTA
-
Ayush Goel
-
Stephen J. Turnbull