James Elliott

Java developers already know Javadoc. Those who’ve been around a long time remember how transformative it was, as Java became the first mainstream language to integrate a documentation generator right into the compiler and standard toolchain. The resulting explosion of API documentation (even if not always great or polished) has hugely benefited us all, and the trend has spread to many other languages. As James Gosling reported, Javadoc was initially controversial because “a good tech writer could do a lot better job”—but there are vastly more APIs than tech writers to document them, and the value of having something universally available has been well established.

Sometimes you need more than API documentation, though—much more than you can fit in the package and project overview pages Javadoc offers. End-user-focused guides and walk-throughs, detailed background on architecture and theory, explanations of how to fit together multiple components…none of these fit comfortably within Javadoc.

So what can we use to meet these other needs? The answers have changed over time. FrameMaker was a groundbreaking cross-platform GUI technical document powerhouse in the ʼ80s. Javadoc even used to include a MIF Doclet for generating attractive printed API documentation with FrameMaker—but only a vestigial Windows version remains. DocBook XML offers similar structural and linking power, with an open specification and cross-platform toolchain, but its raw XML format is impractical to work with directly. Keeping up with its editing tools became expensive and tedious, and even the good ones felt clunky and hampered the flow of writing.

I’m thrilled to have found a better answer: AsciiDoc offers all the power of DocBook in an easy-to-write (and read) text format, where doing simple things is trivial and doing complex things is possible. Most AsciiDoc constructs are as immediately readable and accessible as other lightweight markup formats like Markdown, which are becoming familiar through online discussion forums. And when you need to get fancy, you can include complex equations using MathML or LaTeX formats, formatted source code listings with numbered and linked callouts to text paragraphs, admonition blocks of different kinds, and more.

AsciiDoc was introduced with a Python implementation in 2002. The current official implementation (and steward of the language) is Asciidoctor, released in 2013. Its Ruby code can also be run in the JVM through AsciidoctorJ (with Maven and Gradle plug-ins) or transpiled to JavaScript, all of which work nicely in continuous integration environments. When you need to build an entire site of related documentation (even from multiple repositories), tools like Antora make it shockingly easy. The community is friendly and supportive, and watching its growth and progress over the past year has been inspiring. And, if it matters to you, the process of standardizing a formal AsciiDoc specification is underway.

I like creating rich, attractive documentation for the projects that I share. AsciiDoc has made that so much easier, and given me such rapid turnaround cycles, that polishing and perfecting that documentation has become fun. I hope you find the same. And, coming full circle, if you decide to go all in with AsciiDoc, there’s even a Doclet named Asciidoclet that lets you write Javadoc using AsciiDoc!