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:
- 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
- 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
- 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:
- 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
- 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
- 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:
- 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
- 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
- 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