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 email@example.com 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 firstname.lastname@example.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).
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.
$ 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, you must have the latest stable version of Sphinx installed. The devguide HTML can be built by running:
$ make html
in the checkout directory, which will write the files to the
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.