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. 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:
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/. > > 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 > -- thanks, Abhilash Raj (maxking) _______________________________________________ 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
