6. Helping with Documentation

Python is known for having good documentation. But maintaining all of it and keeping a high level of quality takes a lot of effort. Help is always appreciated with the documentation, and it requires little programming experience (with or without Python).

Documenting Python covers the details of how Python’s documentation works. It includes an explanation of the markup used (although you can figure a lot out simply by looking at pre-existing documentation) and how to build the documentation (which allows you to see how your changes will look along with validating that your new markup is correct).

The documentation built from the in-development and maintenance branches can be viewed from https://docs.python.org/dev/. The in-development and most recent 2.x and 3.x maintenance branches are rebuilt once per day.

If you care to get more involved with documentation, you may also consider subscribing to the docs@python.org mailing list. Documentation issues reported on the issue tracker are sent here as well as some bug reports being directly emailed to the mailing list. There is also the docs-sig@python.org mailing list which discusses the documentation toolchain, projects, standards, etc.

6.1. Helping with issues filed on the issue tracker

If you look at documentation issues on the issue tracker, you will find various documentation problems that need work. Issues vary from typos, to unclear documentation, to something completely lacking documentation.

If you decide to tackle a documentation issue, you can simply submit a pull request for the issue. If you are worried that someone else might be working simultaneously on the issue, simply leave a comment on the issue saying you are going to try and create a pull request and roughly how long you think you will take to do it (this allows others to take on the issue if you happen to forget or lose interest).

6.2. Proofreading

While an issue filed on the issue tracker means there is a known issue somewhere, that does not mean there are not other issues lurking about in the documentation. Simply proofreading parts of the documentation is enough to uncover problems (e.g., documentation that needs to be updated for Python 3 from Python 2).

If you decide to proofread, then read a section of the documentation from start to finish, filing issues in the issue tracker for each problem you find. Simple typos don’t require an issue of their own, instead submit a pull request directly. Don’t file a single issue for an entire section containing multiple problems as that makes it harder to break the work up for multiple people to help with.

6.3. Helping with the Developer’s Guide

The Developer’s Guide uses the same process as the main Python documentation, except for some small differences. The source lives in a separate repository and bug reports should be submitted to the the GitHub tracker.

To submit a pull request you can fork the devguide repo to your GitHub account and clone it using:

$ git clone https://github.com/<your_username>/devguide

In order for your PR to be accepted, you will also need to sign the contributor agreement.

To build the devguide, some additional dependencies are required (most importantly, Sphinx), and the standard way to install dependencies in Python projects is to create a virtualenv, and then install dependencies from a requirements.txt file. For your convenience, this is all automated for you and all you have to do to build the devguide is run:

$ make html

in the checkout directory, which will write the files to the _build/html directory. Note that make check is automatically run when you submit a pull request, so you should make sure that it runs without errors.

Changes to the devguide are normally published within a day, on a schedule that may be different from the main documentation.