littleman.co
Published in

littleman.co

Photo by MILKOVÍ on Unsplash (Edited)

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 3
This 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.adoc

produces 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:

$ asciidoctor-pdf — require=’asciidoctor-diagram’ example.adoc

These are very pretty, but can quickly be customized with an asciidoctor PDF theme. These generate beautifully branded, professional looking PDFs:

Branded PDF

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 docs built on Antora. Very meta.

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:

  1. Write some documentation
  2. Commit the changes
  3. 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.

--

--

--

Simple, Beautiful software development.

Recommended from Medium

Use VSCode and Remote SSH extension to connect to Compute Engine on Google Cloud

Optimal Timeline for Data Structures and Algorithms Interview

Build OpenCV 4.5.1 with GPU (CUDA) Support on Windows 10 (without tears)

Accelerate PyTorch with IPEX and oneDNN using Intel BF16 Technology

Performance: Redis vs Postgres

Sia Community Update — February 2019

Software Value Map (SVM): All a product manager/product owner needs to handle the value, metrics…

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Andrew Howden

Andrew Howden

See https://www.andrewhowden.com/

More from Medium

A-Z DESIGN FREEBIES FOR CREATIVES — ASSETS

7 Books to Renew Your Design Inspiration

Person sitting in library

Creating a Personal Customer Experience Will Set You Apart and Make You Memorable.

Why it is right time to liberate creativity