A System Should Explain Itself
Documentation is often treated as a report written after the real work is finished. That arrangement almost guarantees that the report will fall behind.
A system should explain itself while it is being built.
That does not mean filling the source with noise or generating pages nobody reads. It means designing visible contracts:
- commands with clear names
- help derived from governed catalogs
- runtime checks that prove behavior
- examples that can be executed again
- architecture boundaries that are stated and tested
- documentation linked to implementation evidence
Teaching exposes weak design⌗
A programmer can become accustomed to unexplained conventions. A student cannot. When a system is difficult to teach, the difficulty may be in the subject—but it may also be in the design.
Teaching asks the questions that maintenance eventually asks:
- What is this object responsible for?
- Where does this state live?
- What happens before and after the command?
- Which behavior is guaranteed?
- How can I prove it?
Software that can answer those questions is easier to teach, but it is also easier to maintain.
Evidence is better than confidence⌗
A large project accumulates confident statements. Some are true, some were true, and some describe an intention that never became implementation.
Runtime evidence, repeatable tests, generated catalogs, and reviewed documentation help separate those categories.
The goal is not paperwork. The goal is a system whose claims can be checked.