Week 6: What the docs do not say

Documentation as archaeological evidence — what was written, what was maintained, and what the gap between them reveals.

29 March 2027

Open the slides

Learning outcomes#

By the end of this week you should be able to:

1. audit a project’s documentation estate and characterise the decay rate of each layer
2. diagnose a project from the divergence between documented and actual behaviour
3. evaluate documentation as a preservation artefact rather than a usability one

Outline#

• The documentation hierarchy: README, API docs, inline comments, wikis, changelogs, issue templates
• Documentation rot: how quickly each layer goes stale after abandonment
• The README paradox: the most visible document, the most likely to describe a version of the project that no longer exists
• Case study: GeoCities — what was lost when Yahoo deleted 38 million pages, and the Archive Team’s scramble to preserve them
• Generated vs authored documentation: what jsdoc output tells you vs what a hand-written guide tells you
• The undocumented feature as diagnostic artefact

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.

Further reading#

• Lethbridge, T.C., Singer, J. and Forward, A. (2003) ‘How Software Engineers Use Documentation: The State of the Practice’, IEEE Software 20(6), pp. 35–39.
• Bowker, G.C. and Star, S.L. (1999) Sorting Things Out: Classification and Its Consequences. MIT Press.

Seminar questions#

1. Owens argues preservation is an act of ongoing interpretation, not storage. Does that make stale documentation a failure of preservation or a record of it?
2. Rank the documentation layers on your dig site by decay rate. Does the ranking hold across the class?
3. Is an inaccurate README worse than no README? For whom?