Devguide Reorganization
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
I haven't looked at the results of this work but it all sounds great! 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.melotti@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
On Tue, Sep 19, 2017 at 2:02 AM, Brett Cannon <brett@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.melotti@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
participants (2)
-
Brett Cannon -
Ezio Melotti