I'm currently revising a number of document templates for my company. One thing we've never had is a formal Architecture Specification, so I'm starting to put one together.
What sort of things do you put into your architecture specs? Feel free to copy and paste a table of contents - that would be helpful. Are there any good templates already available on the web?
I've modeled my Software Architecture Documents (or SADs, which is a double entendre because it is both the acronym and what developers feel after looking at them) -- after the Rational Unified Process's Software Architecture document .
It provides a good template for explaining the high-level architecture and some pointers / descriptions of what should go where. Actually I've found the entire suite of RUP templates invaluable when used correctly (don't be afraid to edit the documents and model it after information you deem useful.
Other than that -- a high level UML diagram of the overall components/packages of the system. Then important sub-components (class diagrams), and if sufficiently complex, some sequence diagrams describing the important interactions among compontents.
The important thing is maintaining a balance between usefulness, brevity, and maintainability -- don't get too caught up in unnecessary details.
How often do you see your architecture changing? Will your team religiously update the document with each refactor/new feature? Will the document last the lifetime of the project? How big is your team? Who is the audience? To what detail do you want to document?
In my experience, a team's formal architectural documents tend to fall by the wayside very quickly. When everyone on the team knows each other and the team is small, I tend to avoid these documents. They get out of date and lead new developers astray. Documents are eeevil. A solid team that openly communicates with each other trumps formal architecture docs any day.
At some point such person-to-person communication cannot scale. You must now correctly chose the level of eeevil documentation that applies to the size and scope of your project. Remember too much formality will mean changing the documents becomes too cumbersome. So much detail may be documented that maintaining the documents becomes onerous. You get out of date docs that stay out of date too long. Too little formality means that the team in Seatle has no idea what's going on.
Medium sized teams could do well with just a wiki. Very large teams may wish to have full-time documentation staff that assist in maintaining extremely formal documentation. At this point, documentation should be more than a convenience and the team should make it mandatory.
