1. 14

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.

    1. 5

      I’ve always liked syntax railroad diagrams and a good example is on https://www.json.org/json-en.html.

      1. 2

        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.

    2. 5

      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.

    3. 4

      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.

    4. 3

      Checkerboard diagrams for joins are my go-to to remember how joins work.

    5. 2

      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)

    6. 2

      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.

    7. 2

      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

    8. 1

      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.

    9. 1

      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:


      This can of course be easily extended beyond Lisp, e.g.: