What is the purpose of documents if not to communicate? Someone might wish to make a few personal notes and the cost is minimal, while the value is high, to that person. When that document starts to be a resource for team planning or communication then it needs to be shared in some way. That’s when the cost of creating and maintaining a new non-code document needs to be considered. When it is referred to by many people over time and can change with some frequency, the cost is very high. Cost is generally proportional to the rate of change of the content. When that content is dependent on some code that can also change, the cost is even higher. That cost can be reduced if the document can be regenerated from the code, directly and on demand.

Determining the value of a non-code document is difficult, but over time the most-referred-to documents for a project can be discovered. The Technical Memo is an excellent starting point for documents. The short and single-subject format is low-cost and easy to maintain. Beware creating documents because of an anticipated future need.

Sometimes the only place a change or requirement is written down in a sufficiently rigorous and meaningful way is in the working code. Any effort spent trying to keep non-code documents in sync is potentially wasted, or at least misdirected. That non-code document that doesn’t express the meaning as accurately as the code is a potential source of conflict. In many cases, the only place that being correct really matters is the code. All other versions and descriptions of the function are really subservient to what the code says and how it behaves.