I am probably one of the longest time users of Adobe FrameMaker in the world. I started using it at version 2, sometime around 1990, and finished with it a few months ago. For most of this period it was the unbeatable desk top publishing solution for ‘serious’ documents and books (as opposed to magazine articles and the like). It was used by Sun Microsystems, IBM, and still I believe, HP for their technical publishing. The IMIA yearbook was historically published using it. Thousands of software and engineering companies around the world used it to publish manuals. It did a pretty good job of multi-channel publishing, at least to PDF and HTML, using WebWorks (now ePublisher), and was unbeatable for control over fonts, layout, cross references, and most other details of publishing.
Why did I stop using it?
Well. It’s still very expensive. It’s getting clunky to use. Bringing new users on-board means non-trivial training. It does DITA / XML, but many in the technical development world are losing interest in XML (I’ve always loathed it as one of IT’s worst invention, so no personal pain there). It isn’t available on Mac OSX or Linux.
Amazingly, the latest version (12) doesn’t even display properly on a modern hi-res laptop screen (Dell XPS) – like Adobe Acrobat, if you have a modern laptop with a slightly less modern second screen attached, the menus and UI in general is a complete mess. I spent some months trying to convince Adobe to look at this problem, to no avail. So much for Adobe knowing about graphics.
But the biggest issue is to do with being able to easily integrate multiple sources, including manually authored text, diagrams, UML diagrams from tools, tool-generated model / API documentation, bibliographies and so on. Today, a technical document consists of all kinds of content, which needs to be processed to create a document with seamless heading numbering, cross-references and so on, and then further processed into final output formats like HTML, PDF and DocBook. Having all the content stuck inside one tool, in either a proprietary format or else a difficult XML structure based on DITA or one of the other document XML standards, isn’t conducive to building content from multiple sources, especially where some of those sources are syntax files or excerpts.
Historically, the openEHR specifications have been published in FrameMaker, for nearly 15 years. Ten years ago and probably even by 2010, they were still the best quality technical specifications in the e-health domain, due to Frame’s publishing quality. But now, the problems listed above are starting to bite. In the end it was clear we needed to move to a new solution.
Colleagues pressed me to look at something called Asciidoc, which is one of the many Markdown kind of things around today. I wasn’t positive – I mostly hate markdown (and I’m not alone), because it’s non-standard and grossly simplifies publishing to a mindlessly childish level – headings, lists, links and code blocks. But eventually I gave in and started messing around with an implementation called AsciiDoctor.
First impressions were not good. On this page on the AsciiDoctor site are quotes like the following:
Then why, oh why, do we make it more difficult by burying the content in XML schemas like DocBook, allowing complex word processors to distract us or wasting time battling with finicky WYSIWYG editors?
Imagine if writing documentation was as simple as writing an email.
And also this:
When you’re in the writing (i.e., typing) phase, you want the words to flow onto the screen with minimal distractions and interruptions. Flow, not just time, is essential.
Most word processors excel at distracting you from writing. The result: you write less(ironic, huh?).
You write an AsciiDoc document the same way you would write a normal text document. There are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats.
Hm. Most people who do any real document authoring and publishing with recognise the statements above as mostly nonsense. Good word processors don’t get in the way of writing. Maybe old versions of Word, or WordPerfect. Modern tools like Frame or Word 2013? Not at all. You can use templates that will make decent choices of layout, fonts, and most other formatting choices. So that’s not the problem.
Can writing a complex technical document really be just like writing an email, with no ‘weird format notations’ or tags? Not really. As soon as you want sophisticated content, like centred Figures with referenceable captions, headings that are numbered numerically in the main part of a book, but with letters in the Appendix section, and citations that are shareable across books, you’re going to need something special in the text to indicate these things.
And just consider the challenge of cross-referencing – there is no way to just write them directly into the text. Xrefs are always going to be some sort of technical markers, and tools are needed to find them and offer you the ones you need in the text you are currently working on.
So I have to admit to being quite cynical when embarking on the Asciidoctor journey. Imagine my surprise when it turned out that the tools worked very well, and enabled most of the features I have been used to from Frame for 20 years. To do this, there is sophisticated markup, numerous rules about formatting, and many macros. All within plain text. To get an idea of what a book looks like in Asciidoctor, have a look around this Git repo. Here’s an example of a document created as an Asciidoctor book. This document was created from multiple files (here and here), some of which are tool-generated from a UML tool.
If you have a careful look, you’ll see that there is in fact quite a lot of markup and macros:
Plus a ton of style-sheets for HTML and PDF output stages. No, this isn’t simple at all. Have a look at this user manual to get an idea of how simple it isn’t (lucky this manual is generally excellent isn’t it? You don’t need a manual this big to tell you how to write an email do you?)
The real power of Asciidoctor is that it supports the integration of multiple sources of content into multiple publishing targets. You can include Antlr4 files, generated UML diagrams and class definition tables and a lot of other things. Syntax, either inline or externally referenced will be colourised if there is a lexer for the syntax.
The tools are not perfect, but they are very good and getting better. PDF generation is somewhat weak right now, but the Asciidoctor developers are a) very responsive and b) very knowledgeable about ‘real publishing’, and working hard on it. I expect big things from the next release (at the time of writing we are using 1.5.2).
We have now converted all the openEHR specification documents to Asciidoctor format. What’s better now:
- as a text format, Asciidoctor is treated by version control systems in a comprehensible way to human authors
- syntax fragments are now properly and automatically colourised, a huge improvement over FrameMaker
- separate grammar files can be included directly, and they get colourised as well. Very nice.
- large books can be cut up into multiple files, in various directories
- ‘variables’ can be defined and used, more easily than FrameMaker
- including external files, including those generated by tools is much easier than with Word processor tools
- did I mention the support? Try getting support from Adobe some time to really appreciate the quality of the Asciidoctor team.
What’s not so good:
- defining and using cross-references is quite primitive right now. This needs tool support; hopefully someone will do some work on it.
- Referenceable ‘markers’ can’t be defined like in FrameMaker yet, but I believe are in the works.
- PDF output formatting is very rough, and file size is far from optimal. This is one area where it’s hard to compete with Adobe of course…
- Management of citations is manual, and there is no way to have a shared bibliography that is processed into the correct bibliography for each using document, i.e. just the list of items actually referenced in the document. But this doesn’t come with Frame either…
A ‘neutral’ point is that editing is now done in the source form, so you need two screens to keep track of what the output looks like. This is a blessing and a curse. The upside is that you can use a text editor of choice, like Brackets, which knows about multiple files and even multiple books, and can do very nice regex and normal search and replace across the whole lot. The downside is… you’re hacking around in a lot of ‘markdown’, and always trying to remember the format rules for URLs, bullet lists, code blocks and so on – since all this varies across the numerous MarkDown variants. No, Markdown is not fun. But it’s liveable, and they say it will be standardised. Progressively generating output HTML for review while authoring is easy enough, especially with Brackets. So all in all, the authoring experience is tolerable.
I like the results we have for openEHR, and I that’s coming from an old-style stickler for quality publishing. I’m very happy we made this decision (certain colleagues and friends will be laughing behind their hands right now).
I now see Asciidoctor as an excellent proposition for general publishing of complex technical works, and would recommend it even for a ‘proper’ technical book. It’s been an interesting journey, and the future looks good.