| Reasons to make the effort to do this in markup: 1. You can build tools to automatically generate these diagrams from existing software quite easily. I've used tools like this to generate diagrams that were impractical documentation (150+ sheets of A4 when printed), but showed class or module dependency hotspots in a way that would have taken weeks to understand from the code alone: a picture speaks a thousand words, and getting your code to give you a picture is useful. 2. You can version control them - and see change history - more easily through a markup/code approach than a GUI approach. When teams collaborate over a complicated piece of design, being able to see who contributed what and when in a diagram is as useful as it is seeing it for a piece of code. I'd argue the first responsibility of a programmer in a modern team is to communicate, and to do so in a collaborative fashion. Code, tests, documentation, should allow easy collaborative understanding, editing and iteration. Diagrams that don't have editable markup make this harder in a small way. 3. The semantics of the markup actually make you think through what it is you're trying to express. It's easy to draw a line connecting two shapes but what does that line actually mean? I find when I'm typing up markup for a diagram, this becomes something I more consciously consider. 4. A markup standard means there is likely to be multiple tools that support the reading, editing and creation of the artifacts you create. Some people feel it's easier to use a WYSIWYG word processor, but I think we can all agree that Markdown is a useful innovation that has stimulated some experimentation and development in the text editing domain. 5. Most "hand-drawn" GUI-based diagrams look ugly (most programmers can't design diagrams well), but using an algorithm to make layout choices provides consistency and better layouts. 6. Many "hand-drawn" diagrams are full of style inconsistencies. With a markup + parser = diagram approach, you can enforce a house style, update that style easily, and everybody's diagrams in a doc look aesthetically similar rather than each individual's personal preference on line weights and arrow styles. It's a bit like separating HTML and CSS - hard to do in a GUI-only approach. In larger teams with a dev wiki, all the diagrams looking similar is just nicer. YMMV, but I'd give this approach serious consideration - this tool looks great, but there are others, and it's worth evaluating them if one doesn't impress you. I'm a graphviz guy, but I might consider looking at this more closely. |
Got a hairy state machine? Stick a comment at the top with something like nomnoml's syntax and anyone can follow what's going on without having to trace through the code.