We are starting a refactoring of the devguide into a broader Contribution Guide. Our goal is to recognize, enable, and encourage all types of contribution. Initially we’ll be making it clearer how to contribute to the documentation by providing separate paths for code and docs contributors. Other types of contribution can be added in the future.
Eventually, there will be only one guide, the Contribution Guide. But while the refactoring is in progress, our plan is to keep the existing devguide as it is and build out the new guide in parallel. The work will happen in the existing devguide repo. We’ll provide details here about how you can see the published contribution guide as it develops.
Once the refactor is nearing completion, we’ll switch over to having just the Contribution Guide. The old devguide url and links will be redirected to appropriate places in the new guide to minimize disruption.
Comments are welcome, of course, either here or on the work itself. Help will be appreciated as well!
We are not intending for the final URLs to be devguide.python.org/contrib/get-started. Nothing is written in stone, but our current plan is to have contrib.python.org as the canonical URL for the new guide, with reasonable URLs for the pages. devguide.python.org would be redirected, and existing devguide URLs would also be redirected someplace analogous to their current content.
We have to see how smoothly we can keep two versions going in parallel during the refactoring.
We started moving the internals documentation out of the devguide and into the main cpython repo. The idea is that by being there it can be versioned (the devguide doc tries to cover multiple versions simultaneously) and it will be kept up to date along with the code (in the same PRs).
Thanks, yes, we discussed this as a separate project underway to move some content out of the devguide. It’s great that the code-related details will be closer to the code now. This is in keeping with the tradition of documenting other internal details in the code repo, like Objects/dictnotes.txt.
This is a bike-sheddy suggestion: contribute.python.org would use a full word for the activity, aligning it with discuss.python.org’s use of a full word for the activity.
Probably a minor concern, but when I see “contrib” in a URL or filepath I usually think this is about third-party contributions not officially maintained by a project. Think the “contrib” repository for Debian. “devguide” on the other hand is pretty much unambiguous.
Not everyone who contribute are “kids”, so it is not inclusive to optimize just for the kids who don’t type while making it difficult for others who rely on typing things out. It should be easy for as many group of people as possible.
Browsers might have different behaviors with autompletion and the history, so we shouldn’t rely solely on that either.
I know of others who say things out to their phone and let their phone type for them. Well it doesn’t work as well for me due to having foreign accent, so I myself still rely on typing things out (which causes a lot of typos but that’s a different story).
Anyway, I think the choice of URL should be discussed on its own thread/issue, so we can focus back this discussion about the content and the reorg of the devguide/Contribution Guide here.
Let’s try to move this conversation back to the types of contributions. We have many folks who contribute to CPython in many ways. The refactor will be to provide information specific to these contribution areas. A few areas that have been identified so far:
CPython source code (language and standard library)
