Embracing Agile Modeling
I used to love writing documentation. I was a little different than the average developer I guess. I felt like the more I wrote, the better the documentation was. The height of my excitement was writing a 150+ page functional specification for a product I was doing the architecture and requirements gathering for. I loved sending those huge emails with my document attached. I loved hogging the printer for an hour before a meeting printing out copies for everyone. In short - I guess I just felt like I worked really hard, used words that were hard for others to understand, and had the coolest Visio diagrams. For some reason I really enjoyed that.
I was an idiot.
No one ever read that document and the document was mostly out of date when I was required to “freeze” it. What a waste. Thinking back on it, it would have been a waste if it was half the size. It would have probably been a waste if it was 1/10th of the size.
I decided to completely shun documentation after I realized how much time I wasted (both mine and co-workers) on that document. For a long time I avoided writing documentation at all costs. The great thing about looking for work-arounds from writing documentation was that I found a whole world of great tools that can generate documentation and remove the repetition out of much of the useless documentation that most development shops require.
Like it or not, there are many times that documentation is needed (although a good conversation can replace most of what we normally document).
I recently started a project and took the Agile Modeling approach by Scott Ambler. I can finally say that I’ve found a great middle of the road approach to documentation and modeling. I’ve started giving in and writing documentation (when it’s justified) and I feel like I am producing documents that are valuable.
It’s amazing how readable and useful a document can be when you cut out all the useless shit and put in the stuff that really matters.
March 6th, 2006 at 1:41 am
Hey Ben,
I am going to try this with my next project. Any tips for people starting out? One of the problems that I run into is that as the project veers on, the class diagram veers aaway from the planned UML class diagram and the reasons for the change remain undocumented. Does the Agile modeling help any with that?
Thanks.
Rishi
March 6th, 2006 at 1:42 am
The biggest tip that I have is to actively think about eliminating waste. Forget about freezing your designs and try and get into the mindset of “organic architecture” and let your designs evolve as you learn (about the system, culture, constraints, market, etc.).
Agile Modeling helps because it focuses on improving communication rather than contributing novels to for everyone to daydream over.
My suggestion would be if you need a rigidly defined class diagram and you need to document why it changes - then find a way to do it. I think the ideal situation (at least in my mind) would be to keep the class diagram on a whiteboard (or wiki) and change it as it needs to be communicated to the other team members. Another alternative would be to generate the diagram as part of the build process so that it is alway up to date.
Maintaining a design and evolving code requires too much duplication if it’s not needed. If the intent is to think through scenarios and to “model storm” then a whiteboard is a great place to start. In my experience, it’s usually a good place to end as well.
Let me know how you end up approaching it. I’m always interested in hearing how others work to change these issues that we’ve overlooked for so long.
June 12th, 2006 at 3:51 am
beautiful online information center. greatest work… thanks