As a senior engineer in a large(ish) remote organization, I’ve had to lean on diagrams more and more to communicate software design. A picture really is worth a bunch of words.
I’ve previously worked on smaller, co-located teams where diagramming was pretty rare, perhaps a whiteboard session every now and then.
With a large org, more teams, and more moving parts, less of the application can fit in everyone’s heads. Shared understanding takes more effort.
Illustrating how the pieces fit together, both now and future, may be key to reaching consensus.
I almost always start with pen and paper. I might go through 3-5 drafts before I go to a diagramming tool.
When possible, I prefer to codify the steps. PlantUML looks pretty dated and there’s a small learning curve, but it’s pretty effective plantuml.com
MermaidJS is similar, looks nicer, and has an online editor mermaid-js.github.io/mermaid/#/
Describing a diagram in code such a time saver; very little energy wasted on point-and-click, drag-and-drop, positioning.
Extra points if you can commit the diagram source code to a repo or otherwise share it through a tool like Confluence, which can also embed the diagram output. Makes collaboration possible.
When it makes sense to draw something manually, I like (formerly draw.io) app.diagrams.net
If you belong to an org that pays for stuff, then try Lucidchart lucidchart.com
