Creating diagrams for documentation can be a pain, and more critically it interrupts the flow of writing. There's a way to create these diagrams in AsciiDoc without having to open a separate application. Actually, there are a few ways, I'll just give the most well-known example: ditaa - diagrams through Ascii art.

ditaa is a small command-line utility written in Java, that can convert diagrams drawn using ascii art ('drawings' that contain characters that resemble lines like | / - ), into proper bitmap graphics.

There is a filter available for AsciiDoc that will process blocks of text that are marked as ditaa diagrams using ditaa and insert the result as an image.

Here's how you could create the first diagram from the TicketMonster tutorial using ditaa within AsciiDoc.

You might be thinking that getting all those pipes lined up is a bit of a pain. The first trick is to enable arbitrary positing of the cursor so you don't have to hit the space bar a zillon times. But even better than that, there's AsciiFlow -> http://asciiflow.com.

Just thought I'd give you a heads up.

p.s. The ditaa-AsciiDoc integration could be useful for the CDI specification as well.
--
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597