On Tue, Sep 19, 2017 at 2:02 AM, Brett Cannon <br...@python.org> wrote:
> I haven't looked at the results of this work but it all sounds great! > https://github.com/python/devguide/pull/263 and a few other minor PRs are already merged, but there is still a major one waiting for review: https://github.com/python/devguide/pull/265 In the past few days I've been working on updating the bug tracker, so I haven't worked on the devguide. I plan on picking that up again once I'm done with the tracker. By the time you are back from your month off there should be more PRs waiting for review :) > Thanks to everyone who worked on this! I really appreciate and support the > shift towards "getting things done"-focused docs in the devguide where > lower-level details get shifted in an appendix section that people can > reference as necessary/desired. That should definitely make the whole > devguide less intimidating and easier to digest for those who come to it > for the first time without losing relevant reference sections. > > On Fri, 8 Sep 2017 at 11:53 Ezio Melotti <ezio.melo...@gmail.com> wrote: > >> As you might have noticed, during the sprint I've been mostly working on >> reorganizing the devguide. The bulk of the changes I made affect the >> following pages: >> 1. setup.rst: setup instructions that should be done only once, targeted >> to everybody >> 2. pullrequest.rst: instructions about creating pull requests, targeted >> to everybody >> 3. committing.rst: instructions about accepting/merging PRs, targeted to >> core devs >> >> These three pages cover all the steps from installing git to getting a PR >> merged with upstream. The first two apply to contributors and core devs >> alike, whereas the third is for core devs only. >> >> Unlike most of the other pages in the devguide, these three pages are >> process-oriented, and consist in a sequence of steps that should be read >> from start to finish. People can easily skip steps as they see fit (e.g. >> they can skip "installing git" if they already have it installed). >> >> I also want to make clear in the index.rst page that "reading the >> devguide" -- a currently unfeasible task for most -- should only mean >> reading these two pages (three for core devs). >> >> These pages will contain links to the other "informational" pages -- >> those should be consulted when the need arises and should not be a >> prerequisite reading. >> >> >> Some of the changes I made have already been merged, some are waiting for >> review, and there are several more that I'm planning to do. Some of the >> goals and design principles I'm following are: >> * make the devguide easier to read and navigate; >> * remove duplication and overly verbose sections -- prefer bullet lists >> and to-the-point prose; >> * when multiple options are available, document the one that works for >> most cases; possibly add a footnote or link to a separate section with >> alternative approaches; >> * make information easier to find with ctrl+f, especially in FAQ-like >> pages; >> * prefer few longer pages than many small pages; >> * most pages should have an introduction that explains what can you find >> in the page and the target audience, followed by a concise >> overview/summary/ToCs (should fit in 1 screen), with links to other >> sections/pages that cover the topics in more detail; >> >> Special thanks to Victor, Mariatta, and Carol for the valuable feedback >> provided during the sprint and on the PRs! >> >> Best Regards, >> Ezio Melotti >> _______________________________________________ >> core-workflow mailing list >> core-workflow@python.org >> https://mail.python.org/mailman/listinfo/core-workflow >> This list is governed by the PSF Code of Conduct: >> https://www.python.org/psf/codeofconduct >> >
_______________________________________________ core-workflow mailing list core-workflow@python.org https://mail.python.org/mailman/listinfo/core-workflow This list is governed by the PSF Code of Conduct: https://www.python.org/psf/codeofconduct
