Most people agree that having a whiteboard during a meeting, or having diagrams & charts in a paper is better than not - but I don’t see a lot of discussion about what makes a great diagram / architectural sketch / etc.
If reading is the way to become a better writer, I assume that looking at examples of good diagrams is the way to improve how I communicate visually. So let’s share examples of great diagrams about CS, software, hardware, etc and why we think they’re great.
Alternatively, if there’s a site or book that already has a collection focused on visual explanations of computing concepts that we should know about please share that.
I think e.g. Tufte’s books are probably required reading along these lines, but they are much more general purpose and I’m curious about great examples in computing.
I’ve always liked syntax railroad diagrams and a good example is on https://www.json.org/json-en.html.
Definitely a great visual way to understand syntax.
For anyone playing around with designing syntax, this is a pretty nice online railroad diagram generator: https://www.bottlecaps.de/rr/ui by Gunther Rademacher
You feed it an EBNF grammar and it can output a single XHTML+SVG file or a zip with HTML+PNG – a self-contained page with the grammar visualized as (interactive!) railroad diagrams. It can do little optimizations to your grammar too.
I don’t have a link but I like some pictures that show a linked list in Haskell as a spine made of cons calls and a nil at the end. Because if you change cons to a binary operation and nil to a value you can visually see that a fold corresponds to substituting the constructors by functions.
The visualizations in Railway oriented programming have really stuck with me as one of the best ways to explain the power of Result and Option types.
Checkerboard diagrams for joins are my go-to to remember how joins work.
This was shared here once, but the first time i saw it when when Barry Rountree gave a talk at my school. It’s a plot showing performance variance between processors running at different power bounds. It’s just cool how much data fits into the plot while staying visually clean.
http://shape-of-code.coding-guidelines.com/2020/01/05/performance-variation-in-2386-identical-processors/ (Second plot)
Packet layout diagrams in networking from the RFCs are probably my favorite, but that’s probably because of how much use I got out of them when I was writing packet capture software.
So much of our field is about conditional state and variation that I don’t feel like it lends itself to visualization.
To start, I haven’t read through Bob Nystrom’s Crafting Interpreters, but the diagrams in there are really engaging. I think it’s worth looking at how style and fun can improve on even very well accepted diagrams like parse trees.
along those lines, of course _why’s work is another obvious example
One diagram that I still think of from time to time is from a textbook called Security in computing.
The diagram is nothing special really. And I’m not really a fan of diagrams. It occurs in the part of the book where they explain public-key cryptography. A quite tricky subject, so even though I’m not very excited with diagrams, I felt this one was very useful for aiding the reader to comprehend the material. And I guess that’s what diagrams are for? Not just for the sake of it, but to enhance the pedagogical qualities of the book.
Ref: Pfleeger, C.P., Pfleeger, S.L. & Margulies, J. (2015). Security in computing. (Fifth edition). Upper Saddle River, NJ: Prentice Hall.
The box-and-pointer notation in SICP is a very simple and nice way to visualize how Lisp data structures are laid out in memory:
https://mitp-content-server.mit.edu/books/content/sectbyfn/books_pres_0/6515/sicp.zip/full-text/book/book-Z-H-15.html#%_sec_2.2
This can of course be easily extended beyond Lisp, e.g.:
https://inst.eecs.berkeley.edu/~cs61a/su20/assets/slides/10-Trees_1pp.pdf