What the docs do not say#
SLOP8374 · Week 6
The documentation hierarchy#
- README
- API documentation
- Inline comments
- Wikis, changelogs, issue templates
Each layer rots at a different rate. That difference is the evidence.
Rates of decay#
Inline comments rot first — they sit next to code that changes without them.
READMEs rot slowly, because they are read.
Changelogs stop rather than rot. The date they stop is a date worth having.
The README paradox#
The most visible document in any project is the one most likely to describe a version that no longer exists.
It is written once, at the moment of most enthusiasm, and revised least.
Generated versus authored#
| Type | What it tells you | What it misses |
|---|---|---|
jsdoc / typedoc output | API shape, parameter types | Intent, trade-offs, warnings |
| An OpenAPI spec | Endpoint contracts | Why the endpoints exist |
| A hand-written guide | “Use A, not B — B has a concurrency bug” | Completeness |
| A tutorial | The happy path | Every edge case |
The hand-written guide is the thing you hope to find. Abandoned projects almost never have one.
Reading the gap#
- README accurate, comments stale → died recently
- README promises features the code lacks → died slowly
- No documentation at all → the audience was always one person
The gap between promise and behaviour is the most diagnostic artefact on any dig site.
Case study: GeoCities#
In 2009 Yahoo deleted roughly 38 million user-built pages.
The Archive Team scraped what they could in the months before shutdown. What survived is what volunteers happened to reach in time.
Preservation is not a property of the artefact. It is an act someone performs.
The undocumented behaviour#
Every mature codebase does something nobody wrote down.
Find one on your dig site. Ask why it went undocumented — obvious, embarrassing, or added by someone who assumed they would be around to explain it?
Required reading#
Aghajani, E. et al. (2019) ‘Software Documentation Issues Unveiled’, Proceedings of the 41st International Conference on Software Engineering (ICSE), pp. 1199–1210.
Owens, T. (2018) The Theory and Craft of Digital Preservation. Johns Hopkins University Press. Chapters 1–3.
Before next week#
Catalogue every piece of writing in your dig site.
Find one undocumented behaviour that matters.