Skip to content

Documentation and drift

Whether what is written still describes what exists, and how many copies of it there are.

Documentation and drift

Every hand-maintained copy of a fact is a copy that will go stale, and the reader cannot tell which copy is the current one. This area covers duplicated explanations, references that describe a behaviour the code no longer has, and claims on a page that no test stands behind.

8 moments

Every moment that names this one. Derived from the moments; this page keeps no list.

  1. read three roadmaps for one project and believed none of themA plan kept in prose is a snapshot, and every copy of it drifts on its own schedule; stored status is an assertion that stays true after the world moves. cost: mediumcommon Why, and what to do →
  2. changed a policy in one place and found the old one still in force in three othersA decision is updated at its source and the generated copies keep serving the previous version, with nothing reporting the difference. cost: highcommon Why, and what to do →
  3. read a promise in the README that no test stood behindA sentence describing what the software does is written once and never connected to anything that would fail if it stopped being true. cost: highcommon Why, and what to do →
  4. shipped an interface change whose contract document still described the old oneA contract maintained by hand beside the code it describes goes stale on the first change that forgets it. cost: highcommon Why, and what to do →
  5. pasted a command from the documentation and watched it failExamples are written once, in prose, and nothing ever executes them again. cost: mediumcommon Why, and what to do →
  6. had a green pipeline over generated files that no longer matched their sourcesTests exercise the code and say nothing about the committed outputs derived from it, so the build is green and the artifacts are wrong. cost: mediumcommon Why, and what to do →
  7. found the same thing explained three times, slightly differentlyEvery hand-maintained copy of a fact drifts on its own schedule, and a reader cannot tell which copy is the current one. cost: mediumconstant Why, and what to do →
  8. published a page that promised more than any test could supportPublic material is written by a different act from the code, so it drifts ahead of the behaviour and nothing brings it back. cost: highcommon Why, and what to do →