tag:blogger.com,1999:blog-9099907.post6581478667278298368..comments2021-10-26T20:42:19.297-07:00Comments on Rebecca's Blog: The Value of Design DocumentationRebecca Wirfs-Brockhttp://www.blogger.com/profile/02844092142697047388noreply@blogger.comBlogger2125tag:blogger.com,1999:blog-9099907.post-48561600424128532152009-06-23T21:33:39.657-07:002009-06-23T21:33:39.657-07:00You make a good distinction between system documen...You make a good distinction between system documentation and design documentation. System documentation should be guide for those who follow on. It can (and should) include rationale, restrictions, notes, and general high-level orientation to the system but if it is overly precise it will never match the system's implementation.<br /><br />A wiki that can (and will be refreshed) is a good tool for this. But even with the ease of a wiki, I wonder how many keep system documentation up to date. It is just a discipline that has to become part of what you value (and part of the rhythm of your work).Rebecca Wirfs-Brockhttps://www.blogger.com/profile/02844092142697047388noreply@blogger.comtag:blogger.com,1999:blog-9099907.post-89287482529817363182009-06-21T23:48:25.533-07:002009-06-21T23:48:25.533-07:00A problem I've frequently encountered is that ...A problem I've frequently encountered is that design documentation often gets confused with system documentation.<br /><br />Your design is an input to the development process. It helps you think through and communicate your intentions.<br /><br />System documentation is an output from the development process. It should describe your application (or architecture, etc) in sufficient detail to orient and guide those who encounter it later.<br /><br />The compulsion to keep the design up to date often results from an expectation that the design should document what you built, rather than what you *intended* to build.<br /><br />Moreover, using the design documentation as system documentation serves even more poorly when enhancing an application. After multiple updates, understanding the system requires reading (and mentally layering) multiple 'design' documents. A better approach is to instead update the system documentation (perhaps on a wiki!) as part of each delivery.Unknownhttps://www.blogger.com/profile/03499342329919439742noreply@blogger.com