Ironically speaking, COVID-19 has sped up digital transformation in many organisations across the whole globe ;P Remote work is the new standard, even if some were far from ready (that's why I call it remote "leap of faith"). Teams are facing the challenge of brainstorming (& tuning, & agreeing upon) non-trivial matters (like the architecture of complex systems) over the wire, using digital collaboration tools, async methods & (presumably) a lot of goodwill.

I can tell you this ain't an easy task. But I'll gladly share a few tips that could help you to succeed with effectively visualising systems' architecture in asynchronous work scenarios. All of them are tech-agnostic & (what is more) not focused on any particular type of solutions.

Let's start with a bunch of general ones:

  1. Set the stage properly - whatever you're going to depict, start with clarifying: the scope, the assumptions, the constraints, the boundaries, what's IN and what's NOT. Note down all the qualities the architecture's supposed to be secured/fulfilled (so you can verify it later) - never assume these things are obvious or can be deduced from a diagram or something
  2. Mark the entry point(s) - even if you're not going to start from the helicopter overview, the receiver (reader) has to be able to (re-)orient himself within the general context; whenever he's lost later (can happen to anyone), he can roll there back (conceptually) and start over
  3. Simple & coherent notation (/conventions) - complexity is supposed to be due to systems innate details, so please make sure whoever's gonna face your work won't be struggling with symbols as well ...

A good architecture ain't just diagrams. A good picture can express a lot of information, but if you successfully extend it with additional information (e.g. in appendixes, comments, property tables) you win twice.

Here are a few tips about proper form to execute the desired function:

  1. Multi-Level-of-Detail - never try to force everything within one picture/diagram; ability to adjust the level of detail on multiple levels and shape smooth transitions between those levels is a crucial skill of every software architect; e.g. you could start with a conceptual map (of key components & their responsibilities) and (in a separate section) dive deeper into details of the most complicated/critical component
  2. Describe the PURPOSE/INTENT - probably the most important advice on the list. Diagrams'/models' goal should not be to describe code-level constructs ("Here's a module named ContextManager. Period."), but to clarify the INTENT of a component. Why is it here? What's the role it plays? What kind of problem (explicitly!) does it solve (which justifies its existence)? Use naming to accentuate the purpose as well
  3. Adjust the scope of information (in your visuals) - make sure you're not playing Cpt. Obvious, but focus on key characteristics of depicted elements (& problems they are supposed to solve) instead. Volume? Capacity? Protocol? Load? Security? Static or dynamic aspects? Logical or physical structure?

Shaping architecture is not only about the information & the form used to encapsulate it. It's also about the process (of "architecting things") - I have some tips related to that field as well:

  1. Democratise "drawing" architecture - if you're using tool X & there's just one person with a write-access license (others are only readers) - this will never be 100% team's owned work (they all feel ownership upon); it's better to use a free/cheaper tool (so everyone has access), but to make sure all can contribute freely
  2. Never-ending work-in-progress - architecture is never done, so don't lose any data you know you'll need tomorrow, e.g., explicitly list open questions, issues to be solved, key observations (& remarks to future-you) - feel free to mark them on diagrams, if needed
  3. Asynchrony, meet synchrony - sorry to disappoint you, but you still need to talk things through - even the best, most skilfully crafted architecture diagrams don't do more than depicting their author's mental models, other readers can interpret them in a completely different way - so there's always a need for a guided walk-through to make sure everyone's on the same page
Share this post