Write outline for docsguide.python.org

[nedbat]

In order to support docs contributors, we want a separate docsguide.python.org book similar to devguide.python.org. Write an outline for this new book, based on material in devguide, plus whatever new material is needed.

[nedbat]

Outline: https://docs.google.com/document/d/1Ajk_Vj3rccJ9ReB7WCNhEnLHQP23iMg7jAFQ-CYKzWo/edit

[ezio-melotti]

The link you posted talks about a Contributor's guide -- not just a Docs guide. Did the scope of the issue change?

Also is there any discussion about creating a separate Docs and/or Contributor's guide.
I'm not entirely convinced this is a good idea:

1. It seems that to create a docsguide we will mostly have to move the "documenting" section of the devguide into a separate guide. This will create two separate places where to look things up ¹, two separate repos, some duplication in CI, etc.;
2. Judging by the linked outline, a contributor guide will have the same issues of the docsguide on top of what seems to be a lot of near-duplication of content (and associated increase in maintenance cost). This also doesn't solve the issue of having a guide specific for docs contributors, unless 3 separate guides are created (dev/docs/contributor).

Footnotes

1. even though having a separate place for docs people makes some sense, they will still have to clone the repo, wrangle git, create PRs -- which are all explained in the devguide. ↩

[nedbat]

Sorry, I missed some info, and agree with you. We had talked about making a separate docsguide, but my proposal now is a single Contributor's Guide with distinct sections for code and docs, and shown in the outline. This Contributor's Guide will take the place of the devguide (or will be the new name of the devguide, depending on how you look at it). My proposal is that there will not be a devguide and a Contributor's Guide; there will be only one guide.

The introduction to the Contributor's Guide will help people understand that it is for multiple audiences, and will help direct people to the appropriate sections.

[willingc]

From a user perspective, we will need to serve multiple audiences:

• Core Team
• Experienced Contributors to CPython
• Experienced Contributors but new to CPython development

Different Contribution Pathways

• Code
• Processes
• Tooling and infrastructure
• Documentation
• Localization
• Accessibility
• Outreach and mentoring

[ezio-melotti]

Turning the devguide into a more generic Contributor's guide sounds good to me (even though I like the name "devguide" :). Is the EB going to work on this directly, or just define the outline and let others do the work, or how is it going to work? Is this something that we should discuss in the next docs meeting?

Currently, there is a table in the contributing section that already makes a distinction between Contributors/Documentarians/Triagers/Core Developers.

The quick reference at the top focuses on contributing code patches. Merging the two into multiple different quick references might be a good first step.

[willingc]

Currently, there is a table in the contributing section that already makes a distinction between Contributors/Documentarians/Triagers/Core Developers.

Yes. I think these could be a good starting point for discussing pathways.

Overall, the front page likely needs to be simplified as well as some of the lead-in pages for sections.

[willingc]

We may also want to give thought to contributing.python.org and devguide.python.org directing to different pages in the doc.

[Mariatta]

I would like to propose adding this new section to the Contributing guide: python/devguide#1389

But I don't know where it would fit.