sandbox/morph-devguide / docquality.rst

The branch 'documenting' does not exist.
Full commit

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).

:ref:`Documenting Python <documenting>` 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 current in-development version of the documentation is available at It is re-generated from source once a day from the Doc/tools/ script as found in Python's source tree.

If you would like a technical documentation style guide, the Apple Publications Style Guide is recommended.

If you care to get more involved with documentation, you may also consider subscribing to the 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 mailing list which discusses the documentation toolchain, projects, standards, etc.

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 simply :ref:`create a patch <patch>` for the issue and upload it. 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 patch 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. 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.

Helping with the Developer's Guide

This developer guide lives in a separate source code repository, but is otherwise managed using the same process as is used for the main Python documentation.