Thursday, September 17, 2009

DRY Documentation

Excellent information from "The Productive Programmer":

Note: Out-of-date documentation is worse than none because it is actively misleading.

Documentation is a classic battleground between management and developers: managers want more and developers want to create less. It is also a battleground in the war against noncanonical representations. Developers should be able to make changes to code aggressively, to improve its structure and allow it to evolve. If you must have documentation for all your code, it must evolve at the same time. But most of the time, they get out of sync because of schedule pressure, lack of motivation (because , let's face it, writing code is more fun than writing documentation), and other factors.
Note: for managers documentation is about risk mitigation.

Out-of-date documentation  creates the risk of spreading misinformation (which is ironic, given that part of its purpose is to reduce risk).
  - Neal Ford

No comments:

Post a Comment