Documenting your software architecture - why and how?
Describe what the code itself doesn't
Another of the sessions that I delivered at the recent Software Architect 2009 conference was entitled "Documenting your software architecture - why and how?" and covered some of the drivers for creating software architecture documentation along with some guidelines on how to do this. As I said in the session, any 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.
As with Broadening the T, I'm going to put one or more essays together that cover the content in more detail. In the meantime, you can view or download the slides.
About the author
Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.
You can find Simon on Twitter at @simonbrown ... see simonbrown.je for information about his speaking schedule, videos from past conferences and software architecture training.
Re: Documenting your software architecture - why and how?
Re: Documenting your software architecture - why and how?
That PDF is ~130MB, which might explain why you're having difficulty downloading it. I need to go back through the original, down-sample the photos and re-PDF it. FWIW, the PDF version has exactly the same content as the images, but I am going to go back and reduce the file size anyway.