« Wide Finder, Two.Oh! | Main | How to customize product colors in Shopify »

2008.05.07

Does documenting your architecture make it high quality?

I just posted a piece to InfoQ on the SEI's new 87 page "Evaluating and improving architectural competence" paper. Towards the end of the report there is a section that discusses principles embodied in the models, expressing that goals should be clearly articulated. One of the examples they used made me chuckle:

Documenting the architecture is likely to lead to high-quality architectures because documentation is essential to effective communication, which is essential to effective understanding and use by the architecture’s stakeholders, which is in turn essential to providing timely and useful feedback.

Don't get me wrong - I love most every aspect of my job, but "documenting the architecture" is not one of my favorite activities by a long shot. Its right up there with filling in timesheets and doing SR&ED claims.

I think part of the problem is figuring out what to document. Most of the stuff I've read suggests spending weeks working through the various architectural views. Obvious guy (aka Heraclitus) says that since change is the only constant, you are taking on a significant maintenance burden in synchronizing the document with the evolving system. Meanwhile, the developers and other architects have filed your treatise in the tl;dr folder.

I agree that "effective communication" is "essential to effective understanding and use by the architecture’s stakeholders", but I'll take providing working code anyday.

TrackBack

TrackBack URL for this entry:
http://www.typepad.com/t/trackback/198107/28836310

Listed below are links to weblogs that reference Does documenting your architecture make it high quality?:

Comments

Feed You can follow this conversation by subscribing to the comment feed for this post.

Post a comment

Comments are moderated, and will not appear on this weblog until the author has approved them.

If you have a TypeKey or TypePad account, please Sign In