Introduction

In Praise of Documentation

• The Promise of "Literate Programming"
• A Lamentation on the Death of Literate Programming
• Bad things that happen when you don't document

Why You Should Document

• Code is Communication
• Accessible, Maintainable, Sustainable Code
• Version Control (e.g. GitHub)

Examples

Examples of Open Source Documentation:

• Python help
• Docstrings
• Unix man pages
• README.md
• Readthedocs.com

Documentation Framework Example:

• Diátaxis

Python Documentation Tool Examples:

• Sphinx
• cookiecutter

Scientific Publishing Tool Examples:

• Jupyter
• Quarto

The Bit About AI (yes, I know, and I'm sorry)

• The importance of text for AI Code Assistant and Agentic Coding workflows

Documentation in "Spec-Driven" Development:

• AGENTS.md
• Agent-OS with Claude Code

Calls to Action:

• Writing Tips by George Orwell
• Please Document Your Code!