Steven E. Newton
Crater Moon Development
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 the individual. When the document becomes a resource for team planning or communication then it must be shared in some way. That’s when the cost of creating and maintaining a new non-code document needs consideration. When it is referred to by many people over time and can change with some frequency, the cost is substantial. Cost is generally proportional to the rate of change of the content. Content dependent on some rapidly changing code, 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 being correct matters is the code. All other versions and descriptions of the function are subservient to what the code says and how it behaves.