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.

      1. 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.

        1. 3

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

          1. 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)

            1. 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.

              1. 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

                1. 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.

                  1. 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:

                    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