Ask HN: How to get better at architecture diagrams I haven't spent a lot of time drawing diagrams of the software I'm building, and I'd like to get better at it. Currently I struggle to find the right level of abstraction, and things like dependencies/data flow/user events all end up jumbled together. Are there any great resources for how to document code with diagrams? |
Practice. Drawing diagrams is no different from playing the violin. There isn't a shortcut. Getting better means sticking with an activity you are bad at.
Good luck.
That said, my advice would be to practice keeping 4+1 in mind (https://en.wikipedia.org/wiki/4%2B1_architectural_view_model).
Few pointers: 1. On one end of the diagramming spectrum there are the formal diagrams. Some need to be drawn, some can be coded (state machines, sequence diagrams, concurrency etc.) using specialized tools or sometimes even general purpose ones like mermaid. I'd first check if the team/group prefers formal/structured diagramming. Quite a few enterprise teams (believe it or not) prefer formal diagrams even today (even if they might be building a react-native Apple Watch application, more so if they are building the verification/certification system of the core of a plant assembly). In such cases, you might need to stick to the style and often cough diagramming tool cough they use. There might also be training required/available from your org. Often these diagrams are used to build a formal provable model of "Data Flow Diagrams", "Threat Models" and Synchronization Primitives etc. and some amount of formalism in the diagrams is expected. Such diagram types need training on the diagrams as well as the software (Sparx, IBM etc.) 2. On the other end of the spectrum are mobile phone captures of Whiteboards or Napkins. Often these are taken up by someone on the team to convert into a formal diagram.
Many might not be aware, but software and system diagrams are often referenced by variety of folks from fellow engineers, QA, documentation, localization to sometimes for marketing, sales/contract/RFP, patent application, M&A process. So knowing how to draw to convey lucidly and succinctly is indeed a good skill to develop.
For latter type of environments, here are a couple of pointers:
1. Don't try to cram too much information in 1 diagram. That's why the 4+1 works well. While UML goes overboard, to explain most systems 4+1 is much better suited.
2. As far as possible, stick to black and white for color and boxes for components and arrows for communication or transformation. Dotted, Dashed etc. can come later. In each diagram, the function of the arrow can change. However, don't mess up the convention or directionality of the arrow in that particular diagram. E.g. If a thick arrow from "A" to "B" indicates A is sending data to B synchronously, then thick arrow from "B" to "A" indicates B is sending data to A synchronously. If A has the ability to read async from B, that can be indicated by using a different arrow type (say a dashed arrow from B to A or a filled arrow-head). And put a legend box at the bottom indicating the difference. Then move to the next diagram type - often when doing that diagram (which is putting you in a different frame of mind), you realize you need to go back and change the earlier one - so thinking about your diagram in 4+1 helps you put in the components at the right level of details as well as purpose. And once you have done your 4+1, you might choose to use only 2 or 3 of the diagrams for your presentation or talk.
To get better at diagramming, practice with a single color pencil and paper - literally. Don't practice with colors (there may be color blind audience members). Second, ask someone whom you've seen present "successfully" to provide feedback on your work. Colors and animations often distract from the key purpose of the diagram - to communicate effectively and give you your time back. You can try diagramming common tools to gain practice - alarm clock, email client, dropbox etc. You know you are getting better when others are able to understand your diagrams about failure cases, or human workflows, or even Network time protocol :)