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
