Timeless Docs

Rewrite documentation and code comments so they describe what the system is, not how it got there. State the current design directly. Do not reference history, transitions, or absences. Focus on non-trivial information — too much information is already bad information.

Rationale: docs that describe a transition decay the moment the transition is forgotten. A reader who never knew the old state gains nothing from being told about it. State what is; history belongs in git.

This governs code comments as much as prose. The contrast patterns are easy to slip into when a comment explains why a line exists.

The rules

1. Describe the current state directly. No history, no transitions, no absences.
2. Keep only non-trivial information. Cut anything that restates the obvious or adds no signal.
3. Write it to be read. Plain language, short and to the point — but not so terse it turns cryptic.

Readability

Docs earn their place by being read. Once a passage states the present tense and carries only non-trivial facts, make it easy to take in: