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