Welcome to Software Development magazine's Agile Modeling newsletter. This monthly e-mail newsletter is a free service for Software Development and SD Online subscribers. If you do not wish to get this newsletter, please follow the unsubscribe directions at the bottom of this message.
In This Issue:
--When Should You Document?
--Recently on the AM Mailing List
--Hot Links
The Agile Modeling (AM) methodology defines principles and practices for effective modeling and documentation. It's important to recognize that you need to create just enough documentation when developing software -- too much not only sucks the life out of the project, but also puts your project at risk for failure. Not enough documentation is also dangerous, because you won't be able to maintain and support the system effectively. In other words, you need to travel light, yet recognize that enabling the next effort (for example, maintenance, support, operations ...) is crucial for success.
So, what are valid reasons for creating documentation?
-- Your project stakeholders require it.
Creating documentation is fundamentally a business decision:
You're investing your project stakeholders' resources;
therefore, they should have the final say on whether their
money is spent on nontechnical expenses. If they ask for a
document, and understand the trade-offs involved (more on
this later), you must create it.
-- To define a contract model.
Contract models define how your system and an external one
interact. Some interactions are bidirectional, whereas
others are unidirectional, making the interactions explicit
to everyone involved. Contract models are often required
when an external group controls an information resource that
your system requires, such as a database, legacy application
or information service. The AM practice "Formalize Contract
Models" states that a contract model is something that both
parties should mutually agree to, document and change over
time if required.
--To support communication with an external group. It isn't always possible to colocate a development team, and it isn't always possible to have project stakeholders available at all times. When you need to work with an external group of people, you need to find ways to communicate with them. Shared documentation is often part of the solution -- along with occasional face-to-face discussions, teleconferencing, e-mail and collaborative tools -- but it should play only a supporting role. Documentation should be a last resort for communicating with an external group, because it's far too easy to misunderstand something that's been written.
-- To think something through. The act of putting your ideas down on paper can help you to solidify them and discover problems with your thinking. This, in effect, extends the AM practice "Model to Understand" into the realm of documentation. What appears clear and straightforward in your mind can often prove to be very complicated when you try to describe it in detail. For this reason, I often suggest that people write comments before they write their code -- a strategy I've followed for years.
Now let's explore very common, yet invalid, reasons for documentation:
-- The requester wants to appear to be in control. People will request documents that they can review and sign off on. Instead, ask them to provide constructive feedback about the working software that your team has built, enabling them to add real, not merely political, value.
-- The requester wants to justify his existence. Ask the requester what he intends to with do the document, why he needs it, why creating that documentation is more important than other work that your team needs to do, if there are more efficient approaches, and so on.
-- The requester doesn't know any better. Many people may not be aware that you can successfully produce software in an iterative and incremental manner without mounds of useless documentation.
-- Your process says to create the document. Although this isn't a problem with agile software processes, it can be with prescriptive processes.
-- Someone wants reassurance that everything is OK. For some reason, people think that a document indicates how well a project is going. However, working software is really the only safe measure of success.
-- You're specifying work for an internal group. Documentation is one way to communicate, but it isn't the best. Instead, consider working sessions with the other group or the use of collaborative tools.
-- Your development contracts are routinely subject to re-competition.
So what? If your primary goal is to develop software, focus on developing software. You're much more likely to perform adequately enough to keep the contract.
I think that Plato said it best: "Anyone who leaves behind him a written manual, and likewise anyone who receives it, in the belief that such writing will be clear and certain, must be exceedingly simpleminded ..." Perhaps a little harsh, but something to consider.
This newsletter has been modified from the my book Agile Modeling: Techniques for Extreme Programming and the Rational Unified Process (Wiley, 2002).
Announcement:
I'm pleased to announce that my new book The Object Primer
3rd Edition: Agile Model Driven Development with UML 2 is now available. Hope you like it.
http://www.ambysoft.com/theObjectPrimer.html
Recently On the Agile Modeling Mailing List:
Are You Ready for MDA?
We discussed the main points of my previous AM newsletter
and the drawbacks of the MDA vision and the tools that
currently support it. The general consensus? The tools aren't
there yet, some of the better tools require you to learn their
proprietary action languages (although perhaps programming
languages such as Java or C# would be a better choice), and
the MDA community is clearly struggling with agile concepts.
Too Ambitious
One poster described his current work situation: He'd been
promoting the idea of modeling to his fellow developers,
most of whom were indifferent. After being assigned as
architect on a new project, he broached the idea of taking
a model-driven approach. Some of the advice list members
offered was to take an iterative and incremental approach,
to focus on people over tools, to not preach modeling, but
instead mentor and coach people, and to get working software
in front of stakeholders as soon as possible.
An Anecdote About Diagrams
One poster shared a story about a meeting he had with
business sponsors. They walked the IT folks through a mess
of a workflow diagram that they'd developed. The IT team
showed the stakeholders how to draw UML activity diagrams,
and after about 10 minutes of whiteboarding, the issues were
resolved. The stakeholders were so impressed with the
technique that they requested that the IT team train them
in the technique.
Hot Links:
Various means of communication are available to software
developers; this article compares and contrasts their
effectiveness.
http://www.agilemodeling.com/essays/communication.htm
To learn more about agile documentation, visit
http://www.agilemodeling.com/essays/agileDocumentation.htm
To learn more about UML 2 Activity diagrams, visit
http://www.agilemodeling.com/artifacts/activityDiagram.htm
Looking for training in an agile approach to applying the
13 diagrams of UML 2? If so, visit
http://www.ronin-intl.com/training/uml2.html
The Agile Alliance homepage is the best starting point for
anyone interested in learning more about agile software
development.
http://www.agilealliance.org
With Agile Model Driven Development (AMDD) you create models
that are just barely good enough to drive your implementation
efforts.
http://www.agilemodeling.com/essays/amdd.htm
Check out the Agile Modeling mailing list at
http://www.agilemodeling.com/feedback.htm
