ThinkComposer. Flowcharts, Concept Maps, Mind Maps, Diagrams and Models
thinkcomposer.com
thinkcomposer.com
If the thing you're making sense of is small, a diagram doesn't add much value and may not be needed.
If the thing you're making sense of is too large or complex, a diagram may not be sufficient; you'll likely need to introduce new simplifying groupings or abstractions, or else the diagram will be a huge sprawling tangle. And the diagram may not be even a good start in helping you to identify what those abstractions or groupings should be.
In graph terms, you want the number of nodes to be moderate, and you want the maximum degree of any node to be relatively low. The graph doesn't need to be planar but it helps if it is. And even if you can draw out your diagram and make sense of it today, as your system/repo/whatever grows in complexity, will it still be diagrammable in six months?
1. As a visual aid during project planning meetings. Basically, in the stage where most initial requirements are on the table, it can really help focus a discussion on which architecture components to build, and how these should interact.
2. As a teaching aid for junior devs. The tough part is thinking of a viable architecture, and making UML diagrams is probably half the work a senior dev would put into actually writing the code. It is however really useful for teaching junior devs, because you can give them a direction while letting them figure out a lot of the details themselves.
3. In documentation, I think few things are as useful as having diagrams explain the components, behavior, data flow, chronology etc. They also look pretty and can "ease up" reading difficult documentations.
That said, except for point 3, and I think a tool like mermaid.js, which enables programmers to write diagrams fast and with little learning effort is much more appropriate.
Nobody actually uses the picture. We only work on one program in that system at a time, and all we need to know are its local inputs and outputs. The Makefile ensures there are no cycles.
It is admittedly somewhat unsatisfying to be unable to grok the whole thing at once. But that's the nature of almost everything in life.
It is still easier to parse diagramms, than it is to parse text. The real problem seems to be the extra work of creating the diagrams amd keeping them up to date.
for you, for me it's not. As I must assume that I am not unique this means there are also others for whom diagrams are not useful and difficult to parse and for whom text is useful and easy to parse.
I'm confused, and I love everything in the title...
https://unijokes.com/joke-6757/
I have no idea how an ad got upvoted so much. Don't look at me!
Their first night, a fire starts in the house. The engineer wakes up, sees it, douses it in buckets of water, puts it out, and goes to sleep.
The second night, another fire starts. This time, the physicist wakes up, sees it, calculates exactly how much water to use to put out the fire, pours exactly that much water on the fire (plus or minus experimental margin of error), puts it out, and goes to sleep.
The third night they decide to search for fires before bed.
The engineer does a quick sweep of the house, convinces themself there are no fires, and goes to sleep.
The physicist searches a while longer, convinces themself there are no fires, goes to sleep.
The mathematician searches and searches, but can't prove there are no fires, and so can't go to sleep. After some thought, they set their own fire and go to sleep, thus reducing it to an already solved problem!
"I do," replies the balloonist, "But how did you know?"
"Well," says the man, "You don't know where you are, or where you're going, but you expect me to be able to help. You're in the same position you were before we met, but now it's my fault."
"How can a post hit frontpage with no comments?" "Because people upvoted it without leaving a comment." - I actually find the answer very enlightening.