- Getting started
- Development workflow
- Issues and triaging
- Documentation
- Testing and buildbots
- Development tools
- Core team
- CPython’s internals
- Status of Python versions
- Python Contributor’s Guide (draft)
- [Plan for the Contributor’s Guide]
- Introduction
- The CPython project
- Issues and triaging
- Documentation contributions
- Code contributions
- Core team
- Accessibility, design, and user success
- Security and infrastructure contributions
- Workflows
Helping with documentation¶
Python is known for having well-written documentation. Maintaining thedocumentation’s accuracy and keeping a high level of quality takes a lot ofeffort. Community members, like you, help with writing, editing, and updatingcontent, and these contributions are appreciated and welcomed.
This high-levelHelping with Documentation section provides:
an overview of Python’s documentation
how to help with documentation issues
information on proofreading
You will find extensive and detailed information on how to write documentationand submit changes on theDocumenting Python page.
Python documentation¶
TheDocumenting Python section covers the details of howPython’s documentation works. It includes information about the markuplanguage used, specific formats, and style recommendations. Looking atpre-existing documentation source files can be very helpful when gettingstarted.How to build the documentation walks you throughthe steps to create a draft build which lets you see how your changes will lookand validates that your new markup is correct.
You can view the documentation built fromin-developmentandmaintenance branches athttps://docs.python.org/dev/.The in-development and recent maintenance branches are rebuilt once per day.
If you would like to be more involved with documentation, consider subscribingto theDocumentation category on the Python Discourse and thedocs@python.org mailing listwhere user issues are raised and documentation toolchain, projects, and standardsare discussed.
Helping with documentation issues¶
If you look atdocumentation issues on theissue tracker, youwill find various documentation problems that may need work. Issues vary fromtypos to unclear documentation and items lacking documentation.
If you see a documentation issue that you would like to tackle, you can:
check to see if there is pull request icon to the right of the issue’s title,or an open pull request listed underLinked PRs in the issue body.If there is, then someone has already created a pullrequest for the issue.
leave a comment on the issue saying you are going to try and create a pullrequest and roughly how long you think you will take to do so (this allowsothers to take on the issue if you happen to forget or lose interest).
submit apull request for the issue.
By following the steps in theQuick Guide to Pull Requests,you will learn the workflow for documentation pull requests.
Proofreading¶
While an issue filed on theissue tracker means there is a known issuesomewhere, that does not mean there are not other issues lurking about in thedocumentation. Proofreading a part of the documentation, such as a “How to” orOS specific document, can often uncover problems (for example, documentation thatneeds updating for Python 3).
If you decide to proofread, read a section of the documentation from startto finish, filing issues in the issue tracker for each major type of problemyou find. Simple typos don’t require issues of their own, but, instead, submita pull request directly. It’s best to avoid filing a single issue for an entiresection containing multiple problems; instead, file several issues so that itis easier to break the work up for multiple people and more efficient review.
For help with the finer points of English technical writing, mention the@python/proofreadersteam in your issue or pull request in any@pythonrepo. If you’d like to join the team,open a core-workflow issuesimilar topython/core-workflow#461.