Documenting your software architecture - why and how?

Describe what the code itself doesn't

Documenting your software architecture - why and how? 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 for information about his speaking schedule, videos from past conferences and software architecture training.

Re: Documenting your software architecture - why and how?

I've been reading you for some time and I like what you write. I must say these latest slides are *great* content. Kudos for the superb job of putting it all together. Unfortunately, I can't seem to be able to download the PDF. (Tried from 2 different PC/networks.) Thanks.

Re: Documenting your software architecture - why and how?

Thanks very much Max, it's always great to hear positive feedback.

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.

Re: Documenting your software architecture - why and how?

You were right. I retried it from home and it works. (Corporate network again...) Thanks again.

Re: Documenting your software architecture - why and how?

(BTW, if you do manage to reduce it in size please let me know. A smaller PDF will be easier to pass around to colleagues and higher ups. Thanks!)

Add a comment Send a TrackBack