Onboarding Strategy: Visible Architecture

Photo taken from Radiospike’s photostream under Creative Commons.

Its Purpose?
Visible Architecture helps new team members form a common understanding about how the patterns and constructs in the system interact. It helps them to identify clearer boundaries of responsibility that should not be crossed. It may describe external or internal systems or devices the application may interact with and how they relate to the system. It may also help them understand how the application is deployed and configured.

How Did We Execute It?
We actually ran two sessions to complete this – one ended up describing the physical architecture and how it gets deployed. The other ended up describing the software architecture and focused on the patterns in the system.

For the physical architecture diagram, we drew on sheets of flip chart paper a box for each machine in one colour, then each executing application in another colour on the machines. We also drew circles around the boxes grouping them and gave them a physical name since the servers are grouped together but each group is distributed around the world. Each unique executable was given a code to which we drew a legend on the side to give them a name. We ended up with nine unique executables (it’s the most minimal set for our application requirements), though with many instances of these based on the redundancy needs and distributed nature of this application.

For the software architecture one we first drew onion ring layers of the systems, added labels to each of them and talked about which how the parts should interact and their dependencies. We applied this to the testing layers as well to demonstrate their dependencies on the onion rings that we just drew and their own set of onion rings. We also talked about the patterns in the system and in which layers you would find them.

Techniques Found Useful For Running It

• Flip chart or whiteboard – It was useful to be able to draw relationships between individual executables to show what parts really communicate with each other, and other ones that communicate or depend on a database.
• Colour codes – Given how busy our diagram got in the end, the colours helped people to easily identify what was what.
• Executable code names –Writing each executable name on every box would have taken a long time and made the diagram more confusing. It was more useful to give them a shorthand code such as XX01 or XX02 and to describe it on the side.
• Onion ring layers – Helped people solidify the boundaries to the system in their own heads.

Why Is It Important?
Architecture diagrams are popular for a big reason in many systems as they help people visualise the larger parts of the system. It forces people to take a broader look at the system and provides a better context for the smaller programming tasks. It helps them raise suspicions when one part of the system starts getting too tightly coupled to another as they can understand where the responsibilities lie.

I’ve found that ad-hoc and lo-fidelity diagrams are much more useful than using one built specifically in a single tool as anyone can adapt them there and then in front of everyone and it helps someone show questions they may not be able to ask.

Next Time I Might Try:

• Team Participation First – Getting team members to first draw up what they see as the patterns might help demonstrate where misunderstandings or gaps in knowledge lie and to have better idea of where to focus the discussions.