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 techtribes.je, 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 techtribes.je:

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 techtribes.je 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! :-)}

Responses[2]

Posted by Simon Brown on 26 February 2013 11:06:00 GMT #