[core-workflow] Devguide Reorganization

[Brett Cannon]

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 at 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 at 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/core-workflow/attachments/20170918/e0b17aff/attachment.html>