A picture is worth a thousand dollars

Do you have a wiki where you work with all the technical documentation on it? Anyone ever read or update it?

A big cash burner for many places is documentation. Before you all scream “Hacker!” I believe strongly you should have some documentation, just not endless pages of it. How agile are your processes if you’re constantly in meetings reviewing reams of documentation which is out of date before it even reaches sign off? I think you can accommodate most technical documentation needs with the following:

- Scrum stories
- Sequence diagrams
- Domain models
- Architectural contracts
- In-line code xml comments

So, in this max-strength SOA series, we saw in an earlier post how a user story defines a discrete piece of work for a Scrum team to deliver within a Sprint. So we can tick off item 1. Next up then are sequence diagrams. I particularly like these as a means for conveying information as they capture not only key components but the interactions between them all without getting too bogged down in the technicalities. You can save yourself literally hours of effort and thousands of dollars by simply thrashing out a decent sequence diagram on the back of a whiteboard or even a napkin.

If you haven’t got a full blown version of Visual Studio with architecture support, then fear not! The nice people over at websequencediagrams.com have created a wonderfully simple sequence diagramming tool and there’s even a “napkin” format. Below is a high level diagram outlining how our blogging service will enable us to fullfil our first user story: Saving blog details:

Save Blog Sequence Diagram

Straight away, we’re getting down to business. Architects, developers, testers, business analysts and project managers alike can take a quick look at the diagram above and have a pretty good idea of how the service will perform the task of saving blog details. They can also discern a little of how the internals of the service might be constructed.

We can see in the above diagram the main actors in a process (Big boxes at the top) and the messages between those actors. We have the freedom to add simple explanatory notes and can define the actual request/response description as is fitting to the actors in play. We can show synchronous and asynchronous messages being sent and also get an understanding for the lifetime of each actor. All this is great because we can now start to FEEL how the system will behave and that means we are getting to a position where we can start to consider development. However, before we jump into Visual Studio, some more documentation is necessary before building a service and that is the service contract which we will look at in the next post.

So, to summarise, sequence diagrams are very simple to create and they provide a weslth of clear, concise information. They save time and cut down on waffle, debate and misunderstanding. Ultimately sequence diagrams reduce cost and also the risk of failure as the project proceeds.