Chapter 23: Further Reading — Documentation and Technical Writing

Annotated Bibliography

1. Procida, Daniele. "Diátaxis: A Systematic Framework for Technical Documentation."

URL: https://diataxis.fr/

The definitive resource on the Diataxis framework for organizing documentation into tutorials, how-to guides, reference, and explanation. Procida explains why each category exists, how to recognize which category a piece of documentation belongs to, and how to write effectively within each category. Essential reading for anyone building documentation systems. The website itself is a model of clear technical writing.

2. Nygard, Michael. "Documenting Architecture Decisions."

URL: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

The original blog post that introduced Architecture Decision Records (ADRs) and the format used throughout this chapter. Nygard argues that architecture decisions are the most important thing to document because they are the hardest to recover once lost. Short, practical, and directly applicable.

3. "Keep a Changelog."

URL: https://keepachangelog.com/

The standard format for maintaining changelogs, created by Olivier Lacan. The site explains why changelogs matter, what makes a good changelog entry, and how to categorize changes (Added, Changed, Deprecated, Removed, Fixed, Security). The format has become the de facto standard for open-source Python projects.

4. "PEP 257 -- Docstring Conventions."

URL: https://peps.python.org/pep-0257/

The Python Enhancement Proposal that defines docstring conventions for Python. Covers one-line docstrings, multi-line docstrings, and the __doc__ attribute. While PEP 257 does not mandate a specific docstring format (Google, NumPy, or Sphinx), it establishes the foundational conventions that all three styles build upon. Required reading for any Python developer writing docstrings.

5. "Google Python Style Guide: Docstrings."

URL: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings

Google's style guide section on docstrings and comments provides the definitive specification for Google-style docstrings, the format recommended in this chapter. Includes detailed examples of Args, Returns, Raises, and Yields sections, along with guidance on when docstrings are required and when they can be omitted.

6. "NumPy Documentation Style Guide."

URL: https://numpydoc.readthedocs.io/en/latest/format.html

The NumPy docstring style guide, widely used in the scientific Python ecosystem (NumPy, SciPy, pandas, scikit-learn). If you are building libraries for data science or scientific computing, this is the style your users will expect. The guide includes comprehensive examples for every section type and explains how the format integrates with Sphinx's napoleon extension.

7. "MkDocs: Project Documentation with Markdown."

URL: https://www.mkdocs.org/

The official documentation for MkDocs, the Markdown-based static site generator for project documentation. Covers installation, configuration, theming, and deployment. Paired with the Material for MkDocs theme (https://squidfunk.github.io/mkdocs-material/), MkDocs produces professional documentation sites with minimal configuration.

8. "Sphinx Documentation."

URL: https://www.sphinx-doc.org/

The official documentation for Sphinx, the most established Python documentation tool. Sphinx supports reStructuredText and Markdown (via MyST), auto-generates API references from docstrings, and produces HTML, PDF, and ePub output. While the learning curve is steeper than MkDocs, Sphinx remains the standard for large Python projects and is the tool behind Python's own documentation.

9. Etter, Andrew. Modern Technical Writing: An Introduction to Software Documentation. 2016.

ISBN: 978-1365436079

A concise, practical book on modern documentation practices for software projects. Etter advocates for static site generators, Markdown, and version-controlled documentation stored alongside code. At roughly 80 pages, it is a quick read that covers the philosophy and tooling of documentation-as-code. Directly relevant to the approaches discussed in this chapter.

10. Gentle, Anne. Docs Like Code. 2017.

URL: https://www.docslikecode.com/

Gentle's book and companion website explore the practice of treating documentation like code: using version control, pull requests, automated builds, and continuous integration for documentation. Includes case studies from companies that have adopted this approach and practical guidance on tooling, workflow, and culture change.

11. "mkdocstrings: Automatic Documentation from Sources."

URL: https://mkdocstrings.github.io/

The documentation for mkdocstrings, the MkDocs plugin that generates API reference pages from Python docstrings. Supports Google, NumPy, and Sphinx docstring styles. This is the MkDocs equivalent of Sphinx's autodoc extension and is essential for anyone using MkDocs for Python project documentation.

12. "Write the Docs Community."

URL: https://www.writethedocs.org/

A global community dedicated to the art and science of documentation. The website hosts conference talk recordings, a comprehensive documentation guide, and an active Slack community. The conference talks are particularly valuable for learning about documentation practices from practitioners at companies of all sizes. The community's guide at https://www.writethedocs.org/guide/ is a comprehensive resource for documentation strategy.

13. Rhyd-Lewis, Rhyd. "ADR Tools."

URL: https://github.com/npryce/adr-tools

A command-line tool for managing Architecture Decision Records, created by Nat Pryce. While the tool itself is a simple Bash script, the repository's README provides an excellent overview of ADR workflows, including how to supersede decisions, link related ADRs, and maintain an ADR index. The approach inspired the Python ADR template system in this chapter's code examples.

14. "OpenAPI Specification."

URL: https://spec.openapis.org/oas/latest.html

The specification behind the auto-generated API documentation produced by FastAPI and other frameworks. Understanding the OpenAPI spec helps you write better API code (by understanding what metadata flows into the docs) and evaluate the quality of generated documentation. Particularly relevant for Chapter 17's REST API work and this chapter's API documentation section.

URL: https://idratherbewriting.com/

A long-running blog by Tom Johnson, a senior technical writer at Google, covering documentation strategy, tools, API documentation, and the evolving role of technical writing. Johnson's series on API documentation best practices is particularly relevant to this chapter's coverage of REST API documentation and developer experience.