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.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
