In Praise of Documentation: Tools, Tips & Techniques for Literate Programming in the AI Age

Stephen

Education, Career & Life
Python Skill Novice
Domain Expertise None

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!

Stephen

Psychologist turned full-stack polyglot Data Scientist with an established career in data analytics, scientific psychology, and project leadership. Driven by values of care, compassion and privacy.