This content was originally conceived and drafted in eXtensible Markup Language (XML)(http://www.w3.org/XML) using a commercial XML editor and occasionally Notepad++ (https://notepad-plus-plus.org). The original XML schema used was the Darwin Information Typing Architecture (DITA) bookmap DTD/schema that IBM open sourced as the DITA Open Tool Kit (DITA OT) (http://www.dita-ot.org).

About halfway through the project, we changed the tools pipeline to use plain text for authoring and to use DocBook XML as simply a transient format, making version control easier with free and open source tool git (https://git-scm.com). With the help of a 184-lines-of-code XSLT 2.0 (http://www.w3.org/TR/xslt20) file and Saxon (http://www.saxonica.com), we converted the DITA XML to AsciiDoc (http://asciidoc.org) markup text in mere seconds with follow-on minor clean up by hand. Then, we were back to writing again with the new tool chain.

We then continued the process of authoring, editing and revising the content using the text-based markup language called AsciiDoc using various free and open source text editors such as Notepad++ and mostly Atom (https://atom.io/). The markup was built in modular pieces following the model of the DITA XML methods with the main AsciiDoc file acting as a module map to the component files using the AsciiDoctor include statement. Although the topic-based modularity was initially due to original information architecture from in DITA XML, it proved helpful, and we maintained the modular architecture of the content throughout the project. For editing review, we added automated HTML5 formatting back to the AsciiDoc text source using a free and open source tool called AsciiDoctor (http://asciidoctor.org) that runs on the Ruby command line (http://www.ruby-lang.org). The HTML file could also be opened by Microsoft Word (https://products.office.com/en-us/word) for reviewers not yet comfortable with text processing. We also used Pandoc (http://pandoc.org/) for conversion of Asciidoctor HTML to MS Word files. Reviewers made change annotations in MS Word that were incorporated into the AsciiDoc source with versioning using git.

For other reviewers and for publishing, the plain text AsciiDoc markup was converted to PDF by transforming the AsciiDoc markup to DocBook XML using AsciiDoctor. The DocBook XML was transformed to XSL-Formatting Objects (XSL-FO) using Saxon and DocBook XSL stylesheets. The XSL-FO was converted to PDF using FOP (https://xmlgraphics.apache.org/fop), an open source XSL-FO engine. The ePub (http://idpf.org/epub) version was made with AsciiDoctor.

Use AsciiDoc for document markup. Really. It’s actually readable by humans, easier to parse and way more flexible than XML.[1]
— Linus Torvalds

At first glance this tool chain may sound complicated; however, like Linus Torvalds, we found working with AsciiDoc far easier than working directly with HTML5 elements, DITA XML, DocBook XML or S1000D XML. This is after having used all of these tagging schemas professionally. So when you have technical training or technical writing projects, we recommend you start directly in AsciiDoc and automatically convert to XML as needed rather than starting in XML. The text files with AsciiDoc markup are easy for human reviewers to inspect and edit. The media get inserted by reference like with HTML and XML. AsciiDoc makes for quicker training storyboards too. The structure offered by the AsciiDoc markup allows easy transformation between formats. AsciiDoc provides semantic markup with abbreviated markup rather than the more verbose HTML and XML elements and attributes. Of course, all such markup scheme implementations may initially be helped by having markup job aids.


1. Reproduced from https://gist.github.com/zmwangx/9987772 under a WTFPL license (http://www.wtfpl.net/).
Image

Line By Line

Here a Little, There a Little, Layer by Layer.

Back to Overview