Having a "fast path" for documentation contributions
pradyunsg opened this issue · comments
This came up in the Python 3.10 release stream -- https://youtu.be/AHT2l3hcIJg?t=5700 for the exact timestamp of when this was proposed in the stream and discussed briefly -- and I noticed that no issue has been filed for this yet so... I'm doing it myself. 😅
I wasn't the person who proposed this, so... there's no bullet list items of what exactly this would be. :)
Looking at the contribution process, which took me ~10 minutes to figure out as someone familiar with where things are in the CPython codebase and Python's devguide.
- Clone CPython, at the appropriate point (usually, just the current
main). - Get set up to build the documentation as described in https://devguide.python.org/documenting/#building-doc
- Make your changes in
Doc/*.rst - When a PR is filed, @bedevere-bot labels it with
type-documentation.
The two main things that I see can be improved:
- Having an overview of the process for personas. Like bullet list of "what do I need to do as a content contributor" "what do I need to do as a content/PR reviewer".
- Document
make serveand use https://github.com/executablebooks/sphinx-autobuild/ in it. (full disclosure: I'm the primary maintainer of that)
When you say « fast path » do you mean for new contributors with a good knowledge about git and rst, and using Linux, so it would look like:
- clone that repo
- edit the file, (telling how to find it)
- build locally (telling how)
- look what it look like locally
- pull request
?
I don't know how to properly do that, there's so many different paths, the one for those understanding git but not rst, those understanding rst but not git, those not understanding git nor rst, Windows / macOS / Linux, ..., ....
The one for those not understanding git nor rst is not a fast path though, it's a "sit down with a cup of tea 4 hour learning new things session".
What about something like:
- clone that repo [click here if you don't know git]
- edit the file [click here if you don't know rst]
- build locally [click here if you don't know make or venvs]
- look what it look like locally
- pull request [click here if you don't know github]
?
Yea, that sounds about right.
It's basically a overview for folks who know roughly how the various tools works, and only need the overview + easy copy paste for figuring out how CPython does things.
This doesn't need to be a bullet list -- a doc with somewhat sequential headings like https://pip.pypa.io/en/stable/development/getting-started/ would work well, if you want to have explanation for new-comers referenced or even have them inline (headings make the page skimmable).