Discussion

7 More Common Mistakes in Architecture Diagrams

ashwinnair99: The worst ones are diagrams that look clean but hide all the decisions that actually matter. A messy diagram that shows the real tradeoffs is more useful than a pretty one that lies

zabzonk: Couple of comments:> This can be as simple as adding a type suffix to a resource name (e.g. Orders Table, Results Bucket)Don't encode types in names. And I disagree somewhat that the names are really needed at all.> Making a “master” diagramI think such a diagram is useful but obviously each top-level "box" in it doesn't need to contain all sub-components.

orthoxerox: The most common mistake I've seen is not agreeing on what arrows represent: control or data. Does A-(customer data)->B mean A asks B for data or A sends customer data to B?Of course, sequence diagrams make it clear with two separate arrows when control and data flow in different directions, but a lot of diagrams are of the "plain old boxes and arrows" variety.

zabzonk: In high-level diagrams, which I think is what is being discussed here, I like to think that A --> B means that A "uses" B in some way, and leave it at that.

gruez: >Don't encode types in names.Why? Hungarian notation probably is probably going too far, but in cases where a single word is heavily overloaded encoding types is helpful (eg. image file, image table, image bucket).

zabzonk: I don't think the type needs to be in the name because it is displayed elsewhere in the diagram, possibly as the object's icon. Plus of course the reasons no-one uses Hungarian anymore - types change.And for your naming, I would probably have something like "Unnormalized orders", "normalised orders", "queued orders", but obviously I can't tell without much more information.

segmondy: yup, A interacts with B with the interaction originating from A.