I’d like to put forward a vision for the future of Python’s documentation, as published at https://docs.python.org, in the hope of building general consensus for two things:
- an idea of what good means in documentation and its application to Python’s documentation in particular
- ways of working that will bring about significant improvements more swiftly
I see a very strong opportunity to bring what I can do, to what I think Python’s documentation needs, and I would like to do more of that work in the next year.
In the past 18 months several key people in Python documentation have worked with me on Python documentation, and I believe it has given them confidence that what I am proposing is a good way forward.
However, in order to pursue this really effectively, I need to secure wider consensus for the direction and approach, so I need to outline that more clearly - which is what I want to do here.
I propose to apply the Diátaxis documentation approach to Python’s existing documentation.
Diátaxis is a methodology that identifies four essential and qualitatively distinct needs of documentation users, and from them derives four distinct kinds of documentation: tutorials, how-to guides, reference and explanation.
Diátaxis proposes that these four constitute a complete map of needs, and consequently also of documentation, and that through the application of the principles it describes, a documentation architecture will emerge that reflects these needs and their relationship.
The Diátaxis website describes all this in more detail and is probably the best place to go for a fuller understanding of this, but I am happy to answer questions here.
Diátaxis prescribes a bottom-up approach to documentation, including documentation transformation of the kind I am proposing. What that means is that its principles should be applied at low levels, of pages, paragraphs and sentences, that eventually this will bring about the architectural patterns it predicts.
The key principles of this approach are:
- success in documentation means following rules, not plans
- documentation work progresses best in small iterations
- every act of documentation should represent a tangible improvement, however small
- there is always a simple and small next action available to us in documentation work
- the correct overall structure will inevitably emerge from the application of simple rules
I am well aware that this can be hard for people to swallow, and for those who have not experienced it in action it is a lot to ask for their consent to an approach that deliberately avoids top-down planning or clear pictures of what the end result will look like. So once again I am happy to answer any questions, but in the end it might be necessary for people to have the chance to see it for themselves.
The basics of this approach are described at Diátaxis as a guide to work.
What it mean in practice is a different kind of workflow for documentation, compared with what’s expected for code - for example, small, rapidly-processed pull requests that don’t represent the final result, but a step in its direction.
- my own experiences that helped formulate and validate this approach
- experience with the iterative approach
Last year I ran some workshops for the PSF on Diátaxis, which were well attended.
In 2023 I turned that into more concrete progress; for example at EuroPython I took part in the documentation sprint and following that landed a number of documentation commits and helped others get their start in contributing to Python documentation.
Some of the documentation commits I made in the last year related to Turtle graphics show both progress towards a clearer arrangement of contents, and the iterative approach of small changes.
https://github.com/python/cpython/pull/107449 is a stalled pull request addressing an article in the Python HOWTOs section, that shows the need for securing better consensus for the direction I’d like the Python documentation to take.
I look forward to further conversations about this, and to being able to help bring about a transformation of Python’s documentation to a new standard of excellence.