This week's book giveaway is in the OO, Patterns, UML and Refactoring forum. We're giving away four copies of Refactoring for Software Design Smells: Managing Technical Debt and have Girish Suryanarayana, Ganesh Samarthyam & Tushar Sharma on-line! See this thread for details.
I work on a development team just starting to use UML. One of the things we would look to use our diagrams for would be to give to new team members to help them get up to speed with our applications.
How is it possible to ensure that the UML is kept up to date. By that I mean when a developer makes a change to the source code to fix a bug or for a new release they often do not go an update the UML diagrams
1) Always model first and forward generate code. Usually impractical, requires excellent forward generation tools.
2) Regularly reverse engineer from code to model. Almost always impractical, models every single method and utility class to excruciating detail so the model is harder to read than the code.
3) Stand over developers with a large stick and remind them to keep models up to date. Might be fun if you're holding the stick.
Seriously, Scott Ambler's Agile Modeling style encourages you to think about what models you don't have to keep. Given the problems above this turns out to be most of them. Incorrect documents are pretty dangerous stuff if you have one of the rare groups who ever reads them. [ September 23, 2004: Message edited by: Stan James ]
A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
You should recognize that you don't need to keep many of your diagrams, that's traveling heavy, nor do you even need to keep them up to date. Good docs are high-level and concise, therefore are far less likely to get out of date. Focus on developing really clean code, you'll find that you don't need as much documentation as you think.
Whenever you use UML, remember that the people who you ask to write UML might not be as proficient in it as you might assume.
I fully agree with Stan's observations. They are almost exactly what happened in one of my projects. It takes extreme discipline to maintain a consistent relationship between your diagrams and code, a discipline that almost often is impractical.
Ask yourself what diagrams are really needed. Typically, some sketches of class and sequence diagrams should be more than sufficient to elucidate fine points.
Instead of emphasizing on UML, try to get your developers to document the code better using Javadoc or even by making them write test cases with proper names. This goes a long way in explaining the code than the diagrams.
One mechanism that I used in a project was to draw the diagrams on a whiteboard as a part of brainstorming and then simply capturing it as an image (with digicams, this is a cinch). That done, you can paste it in your documents, or if it is client-facing, ask someone to redraw it in a popular tool and paste it in the document.
Originally posted by Marc Bautis: One of the things we would look to use our diagrams for would be to give to new team members to help them get up to speed with our applications.
The best way to let new team members become productive I know is Pair Programming with them. That way, they learn the system from experience instead of dull paper and can contribute from day one, for example by asking "dumb" questions. The pair might also want to sketch a JIT UML diagram from time to time, of course.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Joined: Jan 29, 2003
Lest we sound like anarchists who frolic drunkenly around documentation bonfires, let's admit some possible Uses of Architecture Documentation. As you consider what models and diagrams can be discarded, also consider which might have value for the purposes described here.
I’ve looked at a lot of different solutions, and in my humble opinion Aspose is the way to go. Here’s the link: http://aspose.com