Annual Review of README Drift
The README describes how to set up the project. Three of the seven steps are no longer accurate. The README was last updated in February.
Year in review: README accuracy. Period: One year since last comprehensive update. Setup steps in README: seven. Steps still accurate: four. Steps inaccurate: three. New contributor incidents: two (both involving inaccurate steps). Time lost to outdated instructions: approximately 80 minutes across both incidents.
The Drift Pattern
Documentation drift occurs when a document is accurate at the time of writing and becomes inaccurate as the system it describes changes. The document does not change with the system.
Drift is predictable for active projects. Systems change. Documentation is not part of the change workflow unless it is explicitly included.
The Three Inaccurate Steps
Step 3: Install dependencies with npm ci. The project switched to pnpm in March. npm ci produces an error.
Step 5: Create .env file with variables A, B, C, D. Variable C was renamed to C_URL in May. The old name produces a silent failure.
Step 6: Run npm run dev. This command was removed when the startup script changed in June. The correct command is pnpm dev.
The Update Cost
Updating these three steps requires approximately twelve minutes: one minute to identify the errors, eight minutes to write the corrections, three minutes to verify them.
The twelve-minute update was deferred each time a change occurred because documenting changes requires separately deciding to document, which is a different workflow from making changes.
The Recommendation
Document changes at the time of making them. Twelve minutes per change, applied three times, equals thirty-six minutes across the year. The actual cost of outdated documentation was eighty minutes of contributor confusion.
The recommendation will be included in the next meeting. The README will be updated this week.