For the love of Asciidoctor
A case study on Medium about writing documents in Asciidoctor. Ironies abound.
One of the more unusual aspects of being a software developer is the sheer amount of writing involved. Not just the writing of software, but:
- Documentation
- Technical Proposals
- Case Studies
- Call for Papers
- Blogs
Writing software invariably means coming to terms with a very human problem, and the way to express human problems to other humans (especially those who are not software developers) is literarily.
Yak shaving my writing
For me as a software developer used to working entirely in monospace font in editors such as code, vim or when I have to pull it out IDEA writing presents an unfortunate plethora of choice.
One can choose:
- Typeface
- Font Size
- Margin Height
- Heading Height
- Page Structure
- Code Style
- Quote Style
- …
Basically an infinite number of things. As well, given the professional background I have I spend an inordinate amount of time getting these document set “just so” — without ever knowing what “just so” looks like.
The problem is, while I end up with a questionably beautiful document I also end up with a very blank document. The creative parts of my brain that are involved while writing or coding are very different than those in use while I am obsessing over what shade of blue to make the headings. What’s worse, they’re mutually exclusive and I am apparently more addicted to tweaking with blue fonts than I am actually writing content.
As an aside, this is why Medium is such an amazing place to write — the lack of choice makes writing amount the content, rather than god damned blue headings.
Solving the paradox of choice
Autonomy and Freedom of choice are critical to our well being, and choice is critical to freedom and autonomy. Nonetheless, though modern Americans have more choice than any group of people ever has before, and thus, presumably, more freedom and autonomy, we don’t seem to be benefiting from it psychologically.
— quoted from Ch.5, The Paradox of Choice, 2004
I am far more successful writing when the document presentation is almost entirely absent from my thoughts. Things like:
- Git Commits
- Medium Articles
- Plain text emails
- Markdown
All come out in a smooth, easy flow. But critical proposals for the client were invariably late and badly reviewed.
The solution was not more — but less; Asciidoctor! From the asciidoctor.org website:
Imagine if writing documentation was as simple as writing an email.
It can be.
That’s the idea behind lightweight markup languages such as AsciiDoc.
Asciidoctor is a combination of:
- Syntax
- Toolchain
Learning Asciidoctor
Asciidoctor is basically a superset of Markdown. The syntax I use is:
= Heading 1
== Heading 2
=== Heading 3This is paragraph text. I usually break it at 120 chars because
I like the hard breaks, and I'm used to it from development.> This is a quote. Quotes look good in presentation documents;
> Very important.[ditaa,target="a-diagram"]
....
+--------+ +-------+ +-------+
| | --+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+
...
That, in combination with the command:
$ asciidoctor --require='asciidoctor-diagram' example.adocproduces a remarkably beautiful HTML
That’s it! You learned asciidoctor. There’s some more cool bits, but that’s enough to write the vast amount of technical documentation.
Finding new yaks to shave
While Asciidoctor is indeed a massive improvement over Google Docs, Microsoft word or (and I ❤ you for trying) LibreOffice, there are still a few things that are perhaps worth exploring.
asciidoctor-pdf
As mentioned, asciidoctor can output to a number of formats. From the --help command line flag:
[html5, xhtml5, docbook5, docbook45, manpage] (default: html5)However, I haven’t been able to share my love of man pages with all project stakeholders. Instead they like PDFs.
Asciidoctor publishes a tool to export directly to PDF, predictably called “asciidoctor-pdf”. It generates beautifully typeset, well structured PDF files for consumption:
These are very pretty, but can quickly be customized with an asciidoctor PDF theme. These generate beautifully branded, professional looking PDFs:
They’re also extremely consistent, being generated from essentially plain text and somewhat difficult to modify.
antora
Antora is a set of tools used for writing documentation based on the asciidoctor primitive.
It’s exceedingly opinionated about the way documentation is laid out, but allows composing documentation from different sources into a single, cohesive website:
Antora is used for a couple of projects, including:
- Fedora
- OwnCloud
- Couchbase
My own experiments with Antora are just beginning, but it does provide some compelling benefits:
- Venerating documentation specific to a limited set of users, but that draws on a wide pool of existing software and features
- Reusing the same documentation snippets in PDF and documentation websites
- The well supported toolchain of Asciidoctor
It may be remarkably useful in future, particularly for agency developers who compile several different software components into custom software stack.
git
Like most software developers, I track the results of my changes in version control. Though it wasn’t initially, it’s now an extremely natural way of thinking:
- Write some documentation
- Commit the changes
- Subject documentation to review
Putting documentation through the same rigour as code changes allows surfacing disparate ideas about how things should work and why they work they way they do.
Such discussion can go a long way to generating uniformity in how a team understands a system or a given problem, as well as improves the quality of the documentation until such a point where everyone can understand it.
Additionally being able to navigate back and forth through the history of documentation is just as useful as it is with code, and keeping the documentation near the code means that as code changes, so does documentation — in the same PR even.
In Conclusion
In the last year I have been far more successful with my writing, at least in terms of the amount of writing I’ve accomplished. I have had perhaps less time than I had in the years before, but have discovered some tools that make writing a much simpler task than my previous, bespoke attempts.
Asciidoctor provides a promising tool that balances the simplicity of writing with being able to express that writing in a number of different but remarkably beautiful ways.
10/10 Asciidoctor authors.
