Discover The Zen Of Writing (Ascii)Docs

Dan Allen (OpenDevise)
Tools and Techniques
Location: Portland 256 Level: Novice
Average rating: ****.
(4.42, 12 ratings)

Writing documentation is already hard enough. Why do we make it even more difficult by burying the content in an XML schema like DocBook or struggling with finicky WSYWIG editors?

What if you could write documentation just as you write an email? Forget about the layout and styling and just let the thoughts flow? That’s the idea behind lightweight markup languages such as Markdown and AsciiDoc. Both formats are designed for humans, yet AsciiDoc goes further by meeting even the most advanced publishing requirements and technical semantics. AsciiDoc is fully capable of serving as a shorthand replacement for DocBook, which it is capable of producing.

In AsciiDoc, the bulk of document is the content, which you embellish with mild and intuitive semantic markup. Need to insert code? Just reference the location of the source you want to include. Document getting too long? Divide it into parts. Need to merge changes from another author? Easy! It’s just plain text. AsciiDoc is a much easier way of writing documentation. Many O’Reilly authors agree and have adopted it to write their books. You should enjoy the same benefit.

Drop the angled brackets and come discover the zen of writing documentation in AsciiDoc. While the format is human-friendly, plain text, you’ll still be able to output beautiful HTML 5, DocBook and PDF documents—or even a slide deck like the one used in this presentation! AsciiDoc has you covered from first to final draft.

Photo of Dan Allen

Dan Allen


Dan is an open source advocate, community catalyst, author and speaker. He proudly pursues these passions as a Red Hat employee and community member. In his role as Principal Software Engineer, he serves as the Arquillian community manager and draws on that experience to help make a variety of open source projects wildly successful, including Arquillian, Awestruct, Asciidoctor, JBoss Forge and CDI.

Dan is the author of Seam in Action (Manning, 2008), has written articles for IBM developerWorks, NFJS magazine, Java Tech Journal and JAXenter and is an internationally recognized speaker. He has presented at major software conferences including JavaOne, Devoxx, NFJS, UberConf, RWX, JAX and Jazoon and has been recognized as a JavaOne Rock Star, JBossWorld Top Presenter and JAX Hall of Fame speaker.

After a long conference day, you’ll likely find Dan enjoying chatting about tech and community with fellow community members over a Trappist beer.


Sponsorship Opportunities

For information on exhibition and sponsorship opportunities at the conference, contact Sharon Cordesse at (707) 827-7065 or

Contact Us

View a complete list of OSCON contacts