Just a quick update today that came out of some coaching I've been doing with a team that's been relatively successful with agile at scale. They've had challenges around recording architectural and design decisions. What should they keep and how should they record it. There are some that would say that all you need is the code and forget recording anything outside of the code. There are others that believe that every aspect of an application should be described separately to the code.
The answer I've seen work best for large projects and or product development is somewhere in between the two.
My experience is that you need the following:-
- Enough described to be useful and no more
- A low cost of recording this knowledge
- The ability to have the frequently asked questions answered
Here's what I've found works in these areas:-
Enough described to be useful and no more
To address the first point, having an artefact that records the architecture of the system works well. A good architectural record is like a good architecture. It has enough to fulfil it's purpose and no more and follows the architectural principle of form follows function.
Now I've seen some completely useless architectural documents and same can obviously occur with recorded presentations. If the content is poor it doesn't matter how it's recorded it's equally useless. So what should be in the architectural recording. Well there’s some standards about what should be described. I'm still a fan of Philip Krutchen's 4+1 view, it's simple without being simplistic, some have a added a data view. However, the way you describe it is your call. Just keep it simple.
A low cost cost of recording this knowledge
So given that it’s form should be low cost and allow us to easily consume what the key elements of the system are, in the absence of direct access to key team members, I’ve seen one approach work really well. Creating a video recording of the lead architect presenting the key architectural elements to the team.
These session is recorded using a video camera (smartphones are good enough now) in front of a live audience that is made up of the team, ideally in a theatre style conference room using whiteboards, modelling tools with a data projector or smart whiteboards. If you have a remote audience then smart whiteboards work and modelling tools will work better. I've used Papershow pretty successfully if you can't stretch to smart whiteboard. Use a tripod even if you're only using a smartphone, it makes the whole thing look more professional. I've used the glifplus with an iPhone.
The ability to have the frequently asked questions answered
Ideally the audience for the session will have some new team members to ask the "getting started" questions. The key things are being able to record the session as a video and having the audience there asking questions of the architect that are answered.
The question and answer part of the presentations should cover the answers to the typical questions a team has about an architecture, such as; “How do we handle security at the field level?” or “If the application falls over what does a recovery look like to the users?” This may mean some scripting if the team has already some of these things before the session.
In my experience of joining projects or having others join projects I've been leading, these videos become one of the most used artefacts for new joiners.
But we outsource
It works equally well with outsource relationships where either the delivery partner is taking on an application maintenance contract and you’re providing the architectural video artefact or you’re receiving a video back after some architectural changes or for a new application delivery project.
Video architecture artefacts are relatively quick and low cost to re-record, easy to publish and access using the web and collaboration tooling. These video recordings become key artefacts that new team members or those maintaining the application will use.