[tobr]

Diagrams of system architecture usually mystify me. A common issue is that it’s unclear what the various boxes and lines and arrows represent.

Consider that it might be that your way of drawing diagrams only make sense to you; unless you are able to state clearly what a diagram illustrates, you might just be confusing your colleague by using drawings.

[sethammons]

Different diagrams are useful for representing different systems. Some folks also use symbols differently. Determining the flow of the diagram can be hard when some folks use arrows to show "what is next" when others show "data came from here" or "data goes there" (in this way, the arrows mean nearly the opposite thing). Usually adding simple "1", "2", "3" identifiers to the arrow paths help.

A flowchart sometimes is best, a sequence diagram is sometimes more clear, a step by step list sometimes conveys the work in an approachable way.

The act of writing (and drawing!) acts as a forcing feature for disambiguation and makes us organize our own understanding. I think a diagram that only makes sense to the author is a good first step. Next is going over the diagram with others to see how they interpret it and making changes to make it more universally understandable.