http://www.jrothman.com/blog/mpd/2006/03/design-documents-need-pictures.html Management, especially good management, is hard to do. This blog is for people who want to think about how they manage people, projects, and risk. Fri, 18 May 2012 15:02:36 +0000 hourly 1 http://wordpress.org/?v=3.3.2 http://www.jrothman.com/blog/mpd/2006/03/design-documents-need-pictures.html/comment-page-1#comment-292 Charles McKnight Wed, 08 Mar 2006 21:53:56 +0000 http://jrothman.com/blog/mpd/?p=8076#comment-292 One of the common misconceptions that I encounter with documentation of all kinds (requirements, design, etc.) is the lack of understanding of the real purpose of the documentation, i.e., to communicate effectively. The numbers vary in case studies, but the overall trends seem to indicate that while most people will "get it" from a picture, there are a significant number who need the textual explanation. From my own experience, I find that using diagrams to illustrate the "big picture" coupled with supporting text that goes into the details provides the best coverage for all audiences. The ones that only want to get the "big picture" look at the diagram and the ones that need the details dig into the text. One of the fallacies associated with the use of UML (or any other picture-only representation) is that it is a lingua franca that provides all things to all audiences, a fact that is demonstrably untrue (and for the record, I like and use UML daily). However, it seems that most shops either opt for one approach or the other based on the perception that it's too much additional work with little return and requires a lot of work to maintain. While I can attest to the rapid pace of change in software development, in really large systems forgoing proper documentation leads to cost and schedule overruns due to things simply being missed because they were not visible. Smaller systems that lend themselves well to agile development should still make some effort to keep things documented. There's nothing more aggravating to all parties than getting a fair piece down the road and not remembering why that particular path was chosen. I would suggest that while tempo is important, moving too fast is just as bad as moving to slowly. One of the common misconceptions that I encounter with documentation of all kinds (requirements, design, etc.) is the lack of understanding of the real purpose of the documentation, i.e., to communicate effectively. The numbers vary in case studies, but the overall trends seem to indicate that while most people will “get it” from a picture, there are a significant number who need the textual explanation.
From my own experience, I find that using diagrams to illustrate the “big picture” coupled with supporting text that goes into the details provides the best coverage for all audiences. The ones that only want to get the “big picture” look at the diagram and the ones that need the details dig into the text.
One of the fallacies associated with the use of UML (or any other picture-only representation) is that it is a lingua franca that provides all things to all audiences, a fact that is demonstrably untrue (and for the record, I like and use UML daily). However, it seems that most shops either opt for one approach or the other based on the perception that it’s too much additional work with little return and requires a lot of work to maintain. While I can attest to the rapid pace of change in software development, in really large systems forgoing proper documentation leads to cost and schedule overruns due to things simply being missed because they were not visible.
Smaller systems that lend themselves well to agile development should still make some effort to keep things documented. There’s nothing more aggravating to all parties than getting a fair piece down the road and not remembering why that particular path was chosen. I would suggest that while tempo is important, moving too fast is just as bad as moving to slowly.

]]> http://www.jrothman.com/blog/mpd/2006/03/design-documents-need-pictures.html/comment-page-1#comment-291 Lidor Wyssocky Wed, 08 Mar 2006 18:31:05 +0000 http://jrothman.com/blog/mpd/?p=8076#comment-291 The opposite approach (settling only for pictures) is also not encouraged. Many developers are setlling for a set of UML diagrams to express (and think of) their design. A set of diagrams, while necessary, cannot capture all of the important design issues that might be worth a discussion. Thread safety issues, behavioral contract and a bunch of other explicit assumptions and issues are all very hard to capture using the common UML notation. Sometimes, even the rationale for a certain design decision might be worth capturing for future reference. You have to add your own notation, and probably some plain English explanations to such non-trivial issues. The opposite approach (settling only for pictures) is also not encouraged.
Many developers are setlling for a set of UML diagrams to express (and think of) their design. A set of diagrams, while necessary, cannot capture all of the important design issues that might be worth a discussion. Thread safety issues, behavioral contract and a bunch of other explicit assumptions and issues are all very hard to capture using the common UML notation. Sometimes, even the rationale for a certain design decision might be worth capturing for future reference.
You have to add your own notation, and probably some plain English explanations to such non-trivial issues.

]]>