Repository navigation
Feature: move the "quick reference" from the devguide root to a dedicated page under Getting Started #1837
Description
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.
Activity
ezio-melotti commentedon Jun 22, 2026
To add more context, this is the issue where I initially proposed adding the "quick start":
The problems it wanted to address were:
In order to solve these problems, the "quick start" was designed to:
The target audiences were mostly:
However 15 years passed since the "quick start" was added. The devguide, the community, and even the "quick start" itself (now "quick reference") evolved over time. If the issues that quickstart was trying to solve, the target audience, or the priorities changed, then it might be ok to move the "quick reference" somewhere else as long as we don't reintroduce the problems that it currently solves.