Architectural descisions is a part of the software development process that often gets lost over time - at least most of them do. Yes we do make diagrams and solution description, but what about the descisions that were just natural to make? The desciosions that were just obvious? What happens to those in the future - try to ask yourself why you chose a decorator pattern over a facade five years ago - can you remember?

We all make descisions everyday - some are small and some are big. A lot of the descisions we make as software developers or architects are implicit and small. Others are fundemental for the architecture that we are developing.

I've often seen code that were mades just a few years ago (some of it my own), and I've thought to myself:" What were they thinking!?! Did they never learn anything about software architecture or programming?" I might have been right, I might ave learned things along the way - but eventhough the code I'm rewieving is wrong or out of date - there might have been a reason to do so. It just might be that it was the best performing solution back then. So it might have been an active choice and not just some stupid kid that made it.

The point is that if you make a descision that you find important, then why not document it? It will almost certainly help you or others in the future, if anyone ever thinks of changing something in your architecture. So should you document all of your descisions? Well - that would be a waste of time, because a lot of small descisions are made along the way. You probably won't even need to document all of your large descisions either.

The general rules around architectural descisions must be to follow your instinct and experience. If you feel that the descion you've made is important to the system and not documented elsewhere, then it would probably be a good idea to do so. But how do you describe a descision? Well basicly you could just write it on a piece of paper. This would help others understand why you did this and that.

I've read a few articles on the subject and I've found great inspiration in one written by Jeff Tyree and Art Akerman in March 2005:" Architecture Descisions: Demystifing Architecture". See this is what I think that archtectural descisions can do - they can remove some of the "magic" in the understanding of architecture. Tyree and Akerman suggest a descion description template. Their templates covers a lot of areas related to a descision- like the actual descision, the issue (why was this descision made), arguments, related descisions and so on. It can be pretty time consuming to follow all of these steps, but the point is that descions are a like. You can put them into a template and describe them.

It is upto you and your organisation to descide on a template that fits you. This can be done from scratch or by looking at Tyree & Akerman (or the more extensive template [Kruchten et al., 2006]) It's all up to you! The point is that you get the tacit descisions documented.

One of the advantages of following a template, when describing a descision, is that they are easy to overlook and other developers can use the same template and describe their descisions in a simular way, so that they are easy for you to read!

The benefit of documenting architectural descisions is that you and others - in the future - will know why you did it, but choose carefully! You do not want to overdo it! That could lead to more confusion and obscurity than good.

If you want to use my advice for anything is your descision to make :-)