3 ms·

I found there are two types of diagrams I lean on, almost always for higher-level explanation-style documents: 1. System architecture 2. Flowcharts NOTE: I do

I found there are two types of diagrams I lean on, almost always for higher-level explanation-style documents: 1. System architecture 2. Flowcharts NOTE: I don't try to mix the two. Architecture diagrams are the what, not the how. I find a lot of people try to mix them. Beyond this, sequence diagrams are useful. I use these for explanatory documentation, mostly. Like, we have a "architecture guide" for each service we maintain, that usually contains a system architecture diagram, and maybe a flowchart of the "happy path" processing. But these are simplified versions things... like, I usually leave configuration details, like networking and access control out of the architecture guide, and just focus on "what services are interacting with each other directly". Also, LucidChart has an "AWS import" method, that actually works well, but can be a little like drinking from the firehose. It's a solid tool, but mostly as it's own kind of reference document, like, API documentation for your AWS stuff.

zozbot234 5y ago
I'm a bit surprised about the use of flowcharts, specifically. Do they really add much over just writing down the same content in pseudocode notation? From a theory-focused POV, flowcharts are supposed to be essentially complementary to dataflow diagrams. But the latter are often more useful for practical concerns.
- mr_tristan 5y ago
  What's important here is that I'm using diagrams mostly in high level, explanatory documents. For example, the decision nodes will be somewhat vague, e.g., "Does event have good location data?" The details of that question are actually very complex, covering multiple fields from different data sources. But the gist is very much "if we don't know it, we're going to then hit this location subsystem". This is in a processing chain that's pretty complex, so, it's just kind of a basic guide. Most of the consumers of these docs are often engineering managers who want a picture of the system, but aren't performing real engineering analysis. I don't use them for detailed technical analysis. Usually, that just involves code. I find dataflow diagrams can be useful, but even those can be overwhelming, depending upon the audience. Ultimately, I don't think you can just talk about diagramming without the context in which you're using the diagrams. I rarely use diagrams with technical reference documentation these days. I use them with high level explanations or tutorials.

zozbot234 5y ago

I'm a bit surprised about the use of flowcharts, specifically. Do they really add much over just writing down the same content in pseudocode notation? From a theory-focused POV, flowcharts are supposed to be essentially complementary to dataflow diagrams. But the latter are often more useful for practical concerns.

mr_tristan 5y ago
What's important here is that I'm using diagrams mostly in high level, explanatory documents. For example, the decision nodes will be somewhat vague, e.g., "Does event have good location data?" The details of that question are actually very complex, covering multiple fields from different data sources. But the gist is very much "if we don't know it, we're going to then hit this location subsystem". This is in a processing chain that's pretty complex, so, it's just kind of a basic guide. Most of the consumers of these docs are often engineering managers who want a picture of the system, but aren't performing real engineering analysis. I don't use them for detailed technical analysis. Usually, that just involves code. I find dataflow diagrams can be useful, but even those can be overwhelming, depending upon the audience. Ultimately, I don't think you can just talk about diagramming without the context in which you're using the diagrams. I rarely use diagrams with technical reference documentation these days. I use them with high level explanations or tutorials.