Poor mans UML / Emacs Artist Mode
When building or designing software, I love to draw diagrams. I find the old adage “a picture is worth one thousand words” to be spot on.
I also find that the diagrams are the most useful when they are right next to the source code. Having to drudge though a wiki or search though a separate documents folder to find the diagram that refers to the code I am looking at seems like a waste of time.
My go to application for doing diagrams for a long time was OmniGraffle. Omnigraffle is a beautiful application, but keeping a Mac only, (seemingly) binary format in the source code seemed silly. I still use an old copy of OmniGraffle for big system “10,000 feet level” type diagrams, but for specific, smaller class level diagrams I needed something better.
I decided to find a format that I could keep right in the readme file if I wanted. Straight ASCII fit the bill, and few years ago I discovered and started using Emacs artist-mode - I’ve been hooked ever since.
Most people that see me using it either think it’s the most ridiculous thing they’ve seen, or they think it’s the coolest thing since sliced bread.
Additionally, I’ve recently found a nice utility called ditaa. Ditaa can make the generated ASCII art into image files which are suitable for presentations and traditional documentation.
Here’s a movie of how it works:
(To get the middle click to work on Mac, I had to use MagicPrefs)
Here is an example of some basic classes and basic relationships in ASCII:
+--------------------------------------------------+
| Subclass (is a) |
+--------------------------------------------------+
+-------------+ +-------------+
| Human | | Captain |
+-------------+ +-------------+
+-------------+ +-------------+
| |<---------------+ |
| | | |
| | | |
+-------------+ +-------------+
+--------------------------------------------------+
| Relationship (knows about) |
+--------------------------------------------------+
+-------------+ +-------------+
| Radio | | Captain |
+-------------+ +-------------+
+-------------+ +-------------+
| |<-------------=-+ |
| | | |
| | | |
+-------------+ +-------------+
+--------------------------------------------------+
| Aggregation (owned by, owns instances of, has a) |
+--------------------------------------------------+
+-------------+ +-------------+
| Ship | | Captain |
+-------------+ +-------------+
+-------------+ +-------------+
| +--------------<>| |
| | | |
| | | |
+-------------+ +-------------+and rendered using ditaa:
