tl;dr

Please document your code.

The perils of poor documentation

Years later, I learned my early enjoyment for reading what we came to call “docs” was matched by an enjoyment in writing technical “docs”. But I quickly realised other data scientists and software engineers often didn’t share my interest or indeed passion for “the docs”. I often found people either wouldn’t document their code at all, or they would document it poorly, and only under duress. But bad things can happen in companies without good documentation. Documentation is the institutional memory of a company. Without (good) documentation, it becomes difficult to understand a codebase. New colleagues can feel alienated, struggle to quickly learn a new and complex codebase, or be unable to fix or update it. It might take a whole team of PhD-level developers months, even years, to reverse engineer a large legacy codebase, to be in a position to rebuild or replace it.

Why document your code

“Documentation is an often overlooked aspect of data science. It’s commonly left until the end of a project, but then you’re excited to move on to a new project, and the documentation is rushed or omitted completely. However, … documentation is a crucial part of making your code reproducible. If you want other people to use your code, or if you want to come back to your code in the future, it needs good documentation. It’s impossible to remember all your thoughts from when you originally wrote the code or initially carried out the experiments, so they need to be recorded.” (Nelson 2024)

Types of documentation

“Names: Names of variables, functions, and files should be informative, an appropriate length, and easy to read.

Comments: Your comments should add extra information not contained in the code, such as a summary or a caveat.

Docstrings: Your functions should always have a docstring that describes the inputs and outputs of the function, as well as the purpose of that function.

READMEs: Every repository or project should have an introduction that advertises your code and lets other people know why they should use it.

Experiment tracking: Experiments, especially in machine learning projects, should be tracked in a structured way.”

Jupyter notebooks: Your notebooks will be much easier to read if you give them good names, give them a structure, and intersperse text and code.

Nelson (2024)

A brief history of literate programming

A document formatting language
A programming language

Knuth (1984)

Nelson’s advice, especially her advice for how to use Jupyter notebooks, can be considered advice for “literate programming”. Literate programming is perhaps the most commonly recommended genre or style of computer programming for data science. The term “literate programming” was coined in 1984, by the American computer scientist Donald Knuth, later Professor Emeritus at Stanford University (Knuth 1984). In literate programming, written prose is interspersed with computer code, within the same document, called a “notebook”. Knuth suggests literate programming is “inherently bilingual”, because it combines two different genres of writing within the same computer program files: a document formatting language and a programming language. While the basic technical implementation of literate programming will be familiar to most data scientists, the origins and history of literate programming might be less familar.

Google Ngram: "literate programming"
1980s	0.095	0.357	1989	6
1990s	0.320	0.659	1998	10
2000s	0.268	0.594	2000	10
2010s	0.216	0.970	2019	10

A brief history of literate programming

The original WEB system was designed as a “tool for systems programmers, not for high school students or hobbyists”, because the programmer needs to be “comfortable dealing with multiple languages simultaneously” (Knuth 1984).

Jupyter notebooks

“Notebooks — documents integrating prose, code and results — offer a way to publish a computational method which can be readily read and replicated.”

“Prose text can be interleaved with the code and output in a notebook to explain and highlight specific parts, forming a rich computational narrative.”

(Kluyver et al. 2016)

Limitations of Jupyter

Pimentel et al. (2019) analysed 1.4 million notebooks on GitHub and found that out of 863,878 attempted executions of valid notebooks (i.e., notebooks with defined Python version and execution order):

Only 24.11% executed without errors
Only 4.03% produced the same results

They make recommendations for improving the use of Jupyter notebooks.

Solutions to limitations

Jupytext
Marimo notebooks
Nelson recommends using Jupyter notebooks for development work, before refactoring notebooks into modularised Python scripts with accompanying tests (Nelson 2024).

R Markdown and Quarto

Quarto YAML

---
title: "In Praise of Documentation: Tools, Tips & Techniques for Literate Programming in the AI Age"
date: "2026-03-01"
categories: [documentation, talks]
format:
  html:
    toc: true
    code-fold: true
jupyter: pydata
bibliography: refs.bib
---

To render a Quarto document, use quarto render on the command line.

Computer programs as literature

“I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature” Knuth (1984)

Computer programs as literature

“Let us change our traditional attitude to the construction of progams. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do” Knuth (1984)

Computer programs as literature

“The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other” Knuth (1984)

Knuth (1984)

I was frankly astonished when I read these paragraphs. They are a very unusual, and bold, set of arguments for a computer scientist to make. Knuth appears to be flipping the disciplinary association of programming from computer science - whether based in mathematics or engineering (so-called “technical” disciplines or “hard” sciences) - to literature, a non-technical, humanities “soft” discipline. The technical domain of programming is turned into a literary domain.

I find it fascinating to think about how both data science and software engineering could be different, if computer software was considered as works of literature, and programmers as essayists. Or if the hierarchy between technical and literary disciplines was reversed.

For a moment, imagine the words of an outstanding writer, such as George Orwell, were to be applied to programming. Let’s take some advice from Orwell on how to write well.

Rules for good writing

George Orwell (Orwell 1945) considered good writing to be active, precise, and simple.

He argued we should write actively rather than passively, be precise rather than vague, and use simple verbs rather than complex longer words or phrases.

If we can drop a word from a sentence without losing the meaning, we should drop it.

Rules for good writing

Orwell called the use of language a habit. And he made a close relationship between language and thought.

By learning to write well, we can develop good ways of thinking. By writing clearly, we can think clearly, and thereby communicate our thoughts more clearly to others.

The thoughts are in the words, and our thinking is displayed in our writing, so we had better choose our words wisely.

In writing well, we can feel more like a human being, rather than a machine.

Documentation in the age of AI

Spec-driven development
AGENTS.MD
Coding agent CLI or IDE tools can be instructed to read the AGENTS.md and do “spec-driven development” (e.g. Claude Code, Cursor, OpenAI Codex).

Concluding remarks

I hope to have impressed upon you the importance of writing docs, such that you might also be in praise of documentation. When we build data systems, or do data analysis, we are writing text. When we code, arguably, we are communicating. We are writing. Whether to a human or an AI agent. And, when we write technical documentation, we’re also writing. The code we write now will be read by our future selves, future readers of our reports, and future users of our software tools. In writing our code today, we are writing the legacy code of tomorrow. And documentation is a user guide for the data infrastructures of the future. While writing documentation can be technically “fun”, the solution to the lack of documentation is not so much technical as cultural. It is a matter of taking time to care and attention. So, take care of software infrastructures, by writing good documentation! Please …

Further Resources

To read a longer version of this talk, see the blog post @ carecodeconnect.io.

Diátaxis: documentation framework.

man: manual pages for Unix-like operating systems.

Material for MkDocs: MkDocs theme and extensions for fast, searchable, polished project docs.

Pandoc: universal document converter.

Read the Docs: free hosting that builds and publishes documentation from your repository.

Sphinx: extensible documentation generator (reStructuredText-first) used widely in Python for multi-format technical docs.

tldr: concise, community-driven, open-source help pages for command-line tools.

Write the Docs: best practices for creating software documentation and technical writing.

Zensical: static site generator for Markdown documentation sites, from the same ecosystem as Material for MkDocs.

References

Gazzard, A. 2016. Now the Chips Are down: The BBC Micro. The MIT Press.

Kluyver, T., B. Ragan-Kelley, F. Pérez, B. Granger, M. Bussonnier, J. Frederic, K. Kelley, et al. 2016. “Jupyter Notebooks – a Publication Format for Reproducible Computational Workflows.” In Positioning and Power in Academic Publishing: Players, Agents and Agendas, edited by F. Loizides and B. Schmidt.

Knuth, D. E. 1984. “Literate Programming.” The Computer Journal 27 (2): 97–111. https://doi.org/10.1093/comjnl/27.2.97.

Nelson, C. 2024. Software Engineering for Data Scientists: From Notebooks to Scalable Systems. O’Reilly.

Orwell, G. 1945. Politics and the English Language. London: Penguin Books.

Pimentel, J. F., L. Murta, V. Braganholo, and J. Friere. 2019. “A Large-Scale Study about Quality and Reproducibility of Jupyter Notebooks.” In IEEE/ACM 16th International Conference on Mining Software Repositories, 507–17. Montreal, QC, Canada. https://doi.org/10.1109/MSR.2019.00077.

Google Ngram: "literate programming"
Decade patterns (1984–2019), per-billion tokens
Decade	Trend (yearly)	Mean	Max	Max year	Years
1980s		0.095	0.357	1989	6
1990s		0.320	0.659	1998	10
2000s		0.268	0.594	2000	10
2010s		0.216	0.970	2019	10

In Praise of Documentation

tl;dr

How I learned to love documentation

The perils of poor documentation

Why document your code

Types of documentation

A brief history of literate programming

A brief history of literate programming

A brief history of literate programming

Jupyter notebooks

Limitations of Jupyter

Solutions to limitations

R Markdown and Quarto

Quarto YAML

Computer programs as literature

Computer programs as literature

Computer programs as literature

Computer programs as literature

Rules for good writing

Rules for good writing

Documentation in the age of AI

Documentation in the age of AI

Concluding remarks

Further Resources

References