Refactoring the devguide into a Contribution Guide

Documentation
1

We are starting a refactoring of thedevguide 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.

Theeditoral board issue starting the work has some discussion and a link to theproposed new outline for the contribution guide. Take a look.

Eventually, there will be only one guide, the Contribution Guide. But while the refactoring is in progress, our plan is to keep the existingdevguide as it is and build out the new guide in parallel. The work will happen in the existingdevguide 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!

19 Likes
2
Ned Batchelder:

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.

The new URLs are currently under acontrib/ subdirectory:

  • devguide.python.org/contrib/get-started/

The old URLs are of course at top-level:

  • devguide.python.org/getting-started/

Iscontrib/ subdirectory just during work in progress, or is the plan to keep it even when complete?

It feels a bit redundant, and, when ready, would be more ergonomic to move them up a level:

  • devguide.python.org/get-started/

(Edit: fixed last URL)

1 Like
(Ned Batchelder)3

We are not intending for the final URLs to bedevguide.python.org/contrib/get-started. Nothing is written in stone, but our current plan is to havecontrib.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.

5 Likes
4

FYI, to the extent this is related to your work:

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).

This is tracked ingh-119786

4 Likes
5

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.

6
Ned Batchelder:

contrib.python.org

This is a bike-sheddy suggestion:contribute.python.org would use a full word for the activity, aligning it withdiscuss.python.org’s use of a full word for the activity.:sweat_smile:

9 Likes
7

“Contribute” is tedious to type though.

2 Likes
8

browsers have history and auto-completion and kids don’t type anymore (URLs particularly).:wink:

1 Like
9
Ned Batchelder:

Nothing is written in stone, but our current plan is to havecontrib.python.org as the canonical URL for the new guide

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.

4 Likes
(Nice Zombies)10

Contribute is the terminology GitHub uses though (broader than simply the maintainers of the project):

11

I specifically meant the string “contrib”. “Contribute” is fine.

3 Likes
12

Let’s move the name bikeshedding to an Issue, where it belongs. I’ve opened this:Bikeshed: what should the domain name be of the new unified contributor's guide? · Issue #1393 · python/devguide · GitHub

3 Likes
13
Frank Sachsenheim:

browsers have history and auto-completion and kids don’t type anymore (URLs particularly).

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.

(Carol Willing)14
Ned Batchelder:

We are starting a refactoring of thedevguide 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.

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)
  • Documentation including translation
  • Tooling to support CPython releases
  • Tooling and bots to support core workflows
  • User success including accessibility and design
  • Security: SBOMs, best practices, more info
  • Infrastructure: GitHub, runners, websites, etc.
  • Outreach: sprints, mentorship

Please share any additional ideas here.

1 Like