This post originated from an RSS feed registered with Agile Buzz
by Steven E. Newton.
Original Post: Documentation has a Cost and a Value
Feed Title: Crater Moon Buzz
Feed URL: http://www.cmdev.com/buzz/blosxom.cgi?flav=rss
Feed Description: Views and experiences from the software world.
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.
Previous Topic
