Coding the Architecture provides a very nice slide set giving a very good high level overview of why and how to document your software architecture in a practical way. As I wrote, it is a slide set and therefore only provides very short summaries on the different aspects. Nevertheless, it provides some good suggestions which topics should be covered and how to document them.
Key takeaways:
- Software architecture documentation should be complementary to the code and describe what the code itself doesn’t. For example, it’s really hard to identify things like architectural principles, operational aspects and how security works from just the code itself.
- Keep it short and useful
- What it should contain:
- Explanation of the software structure
- The architectural principles and constraints
- Development and deployment technologies and platforms
- A justification of how the architecture satisfies the requirements
You can find the slide set here.
BTW: Coding the Architecture contains a lot of useful resources for software architects.