Describe the enhancement or feature you would like
As the root page has evolved, it has become more clearly an index page, with some high level content but not much detailed documentation, leaving that for other pages. Technical guidance at the level of "run this command" no longer belongs at the root of the docs, except perhaps in summary fashion.
I think we should add a new page to the Getting Started docs, but after "Setup and building" in doc order. The intention being that this is explicitly not a "quickstart guide", and treating it as such should be subtly discouraged.
Describe alternatives you have considered
Initially, I intended to propose we remove the section. The content it covers is fully captured by other pages.
However, the "quick reference" is, itself, unusual in that it spans the concerns of cloning, building, testing, running blurb, and opening a PR. For a new contributor, who may have done only 1-2 PRs already, having an easy reference doc which fits on one page, especially as reminders for those final steps, is useful.
I also weighed the possibility of subtly changing the purpose of the doc, from "Quick Reference" to "Quickstart". There are two reasons I rejected the idea. First, the target audience for this doc is not, in my opinion, brand new contributors. It's for newer or infrequent contributors who benefit from having an easy reference to things they've already learned. The second reason is that the typical implication of a "quickstart" guide is that "you follow these steps and you'll be ready", which seems like the wrong message to send to new contributors.
Additional context
This was inspired out of a discord conversation (ref). @nedbat noted that the "quick reference" section in the index doc is not well-placed. I agree, and think there are a couple of options for what to do.
At first, I thought it was just a git reference doc, and intended to propose removal. Looking closely, I think there is a useful thing here worth preserving. I had never -- as a new contributor -- looked at this bit of doc, and there are subtle details in it which are good reminders! e.g.,
reminds me that I can pass -j <N> to the testsuite.
Describe the enhancement or feature you would like
As the root page has evolved, it has become more clearly an index page, with some high level content but not much detailed documentation, leaving that for other pages. Technical guidance at the level of "run this command" no longer belongs at the root of the docs, except perhaps in summary fashion.
I think we should add a new page to the Getting Started docs, but after "Setup and building" in doc order. The intention being that this is explicitly not a "quickstart guide", and treating it as such should be subtly discouraged.
Describe alternatives you have considered
Initially, I intended to propose we remove the section. The content it covers is fully captured by other pages.
However, the "quick reference" is, itself, unusual in that it spans the concerns of cloning, building, testing, running
blurb, and opening a PR. For a new contributor, who may have done only 1-2 PRs already, having an easy reference doc which fits on one page, especially as reminders for those final steps, is useful.I also weighed the possibility of subtly changing the purpose of the doc, from "Quick Reference" to "Quickstart". There are two reasons I rejected the idea. First, the target audience for this doc is not, in my opinion, brand new contributors. It's for newer or infrequent contributors who benefit from having an easy reference to things they've already learned. The second reason is that the typical implication of a "quickstart" guide is that "you follow these steps and you'll be ready", which seems like the wrong message to send to new contributors.
Additional context
This was inspired out of a discord conversation (ref). @nedbat noted that the "quick reference" section in the index doc is not well-placed. I agree, and think there are a couple of options for what to do.
At first, I thought it was just a git reference doc, and intended to propose removal. Looking closely, I think there is a useful thing here worth preserving. I had never -- as a new contributor -- looked at this bit of doc, and there are subtle details in it which are good reminders! e.g.,
./python -m test -j3reminds me that I can pass
-j <N>to the testsuite.