Repository navigation
Simplify the index page by audience #189
Description
The index page has become rather long and is starting to feel like a wall of text. It should probably be clearly separated into 3 sections:
- New contributors
a. New to open source (e.g. needs help to build Python)
b. Just new to the project (i.e. just needs to know how the project does things - Core devs
- Appendix
Once we do this I think it will help show redundancies that have accumulated over time (e.g. all the git information that we have spread out across the devguide).
Activity
ncoghlan commentedon May 6, 2017
I think the core dev section may also need to be split, although I'm not sure what the two sub-audiences should be called. The way I think of them:
For the first group, the key things to highlight are those points that relate to collaborating with self-motivated volunteers rather than working solely with full-time colleagues as part of a paid development team. Most importantly: don't assume everyone else working on the project is a professional software developer.
For the second group, we may need to be more explicit about things we'd consider "foundational knowledge you should already have learned at work" for a professional software dev (such as how to use a code review tool as a reviewer, or the right terms to use to search for things on Google).
terryjreedy commentedon May 6, 2017
Thank you for identifying the two groups and suggesting that the second group, which includes me, should not necessarily by empty.
pfmoore commentedon May 6, 2017
Agreed - I'd put myself in the second group too. Even though I'm technically a developer, in practical terms the processes used in my line of work are so different from those used in open source that it may as well be a different profession. (Although I've worked enough in open source that the tools are familiar, the processes are most decidedly not).
I'd also point out that for group 2 we should also include reminders that many core devs are in group 1 - which means that they may not even understand the difficulties you're having with the tools and processes, so work with them accordingly.
ncoghlan commentedon May 6, 2017
Attempting a more value-neutral description of the two categories:
With that reworded explanation, I would have been in the "Independent Activity" category when I was still at Boeing, and only considered myself part of the "Procedurally aligned profession" category after moving to Red Hat in 2011.
brettcannon commentedon May 6, 2017
IOW "software development as a job" and "software development for fun" 😉 .
ncoghlan commentedon May 7, 2017
Not quite, as folks in the second category may still develop software as their day job (just with radically different practices & processes - that was the case for me when I was at Boeing), while folks in the first category may still be participating in CPython development out of purely personal interest.
ezio-melotti commentedon Sep 5, 2017
I'm looking into this as part of #120. The 3 main places where the git info are are:
I'm currently thinking about leaving 1 alone (its faq nature doesn't even require separating between contributors and committers), getting rid of 2 (moving relevant parts either in 1 or 3), and keep 3 as a process-oriented section that includes the basic commands and refers to 1 for more advances use cases.
3 could be target mostly to contributors (the workflow they follow is similar to ours) and possibly include a follow-up section with committers-specific instructions for merging (but that shouldn't include any git command).
ezio-melotti commentedon Sep 8, 2017
I made some changes in #263 and #265.
I don't think this is necessary. Since the workflow is now mostly the same for contributors and core devs, the only core-devs-specific information should be in the committing.rst page. The distinction between new to open source and new to the project is also not necessary: the devguide describes all the steps, if people already have git installed or have already built Python, they can just skip those steps.
I already took care of this in #263 -- all the git information are now in 3 places:
In #265 I also removed most duplication between the pullrequest.rst and committing.rst pages.
ezio-melotti commentedon Sep 8, 2017
A different distinction I want to make is:
See also the "Devguide Reorganization" thread on core-workflow.
willingc commentedon Mar 19, 2018
Perhaps this replaces #40. Recommend closing issue #40
willingc commentedon Oct 11, 2023
This is completed by the addition of the table by contributor type.