Sample software guidebook and sketches

Documentation on software projects is often a contentious topic, particularly since the agile manifesto says that we should value working software over comprehensive documentation. My take on lightweight documentation has now been included in my Software Architecture for Developers book and I've had a stream of e-mail requests since publishing the new version to ask whether I would create a sample software guidebook too.

A sample software guidebook

Yes is the answer ... and I've already started putting this together, based upon a side-project of mine called, which is basically a community portal for the IT, tech and digital industry in Jersey*. This is a fun little side-project rather than a huge high-performance distributed system, but it should be enough to illustrate the concepts in the book.

And some sample software architecture sketches

The sample guidebook will also include some software architecture diagrams, which will again serve as an example of the context, containers, components and classes sketches that I talk about. The following context diagram (included in the sample guidebook) provides an overview of

Context diagram for

The introduction and context sections of the sample guidebook are available in the published version of my book now and I'll be adding the other sections over the next few days.

Plus some open source code

As a final note, I'm planning to open-source the code behind on GitHub so that you can see the correlation between the code and the documentation. If there's anything else that you'd like to see in the book, please just drop me a line.

* just to avoid any confusion, I'm referring to Jersey in the Channel Islands, not New Jersey! :-)

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: Sample software guidebook and sketches

Hi Simon, Great blog posts :) Is it possible to follow your blog posts through rss feeds?

Re: Sample software guidebook and sketches

Thanks very much and yes, here's the link ...

Add a comment Send a TrackBack