Are ASCII diagrams worth my time?
ascii, diagram, language-agnostic
Solution
If you use a tool to generate documentation from your code, such as Doxygen, there should be a way to reference an image file directly and have it appear in the generated docs. For Doxygen, the relevant command is \image. This combines the benefits of having an actual image diagram with ease of reference from the source (no need to fire up a heavy program like Word), and also with your auto-generated docs.
Problem
Are ASCII diagrams within source code worth the time they take to create? I could create a bitmap diagram much faster, but images are much more difficult to in line in a source file (until VS2010). For the record, I'm not talking about decorative ASCII art. Here's an example of a diagram I recently created for my code that I probably could have constructed in half the time in MS Paint. ``` Scenario A: v (U)____________(N)_______<--(P) Legend: ' / | J = ... ' / | P = ... ' /d | U = ... ' / | v = ... ' / | d = ... '/ | N = ... (J) | | | |___________________| ```