Lets take a moment to review an apparently trailing-edge technology in some domains that is actually leading edge in the training industry.

General text markup is a trailing-edge technology that has been with us since the printing press and moveable type. Human languages are still a primary means of communicating ideas, and even though written text is a trailing edge technology as a whole, when taking the perspective of components and subcomponents of courseware, distinctions in these supporting text technologies can be viewed as leading-edge status for the training domain, although they are already mainstream technologies in the technical writing and publishing domains.

By text markup we mean information formally distinct from the character sequence of the text. Original markup started with handwritten notes to a typesetter on a piece of paper. Computer markup includes fonts, font sizes, emphasis like bold and italic, et cetera and has many methods that are proprietary and owned by particular authoring tool vendors.

To avoid proprietary lock in to a particular authoring tool vendor, some organizations have moved to markup text in more open markup schemes for encoding text in computers. Further distinctions of text markup technologies have included IBM’s generalized markup language (GML)] [1] in 1969, standardized general markup language (SGML) [2] in 1980, to hypertext markup language (HTML) in 1990.

Text markup began to include semantic markup with eXtensible Markup Language (XML) [3] in the mid 1990s, to Javascript object notation (JSON) [4] in 2001, and to HTML5 [5] in 2014.

By semantic markup, we mean using text markup to indicate the meaning of bits of content rather than the primary focus of earlier text markup on defining its presentation or look. The separation of concerns, of content from layout formatting, helps to reduce training developer effort by automating the layout and presentation formatting.

The refinements in text markup from presentation to semantic have made this technology more leading edge. Other domains have refined their use of semantic-oriented text markup for decades now, making it mainstream for them. For the training domain, however, the use of semantic-oriented text markup is still leading edge.

Let’s consider a few simple concrete examples. Each of these examples shows a different technology tweaking text-based markup. In the end, note that all these examples are encoded in text. Plain, old, long-lasting, text. For those of you wondering how the presentation formatting is done, for now let’s just leave it at a high level. Presentation and layout are accomplished using style sheets. This separation of content and style is the main idea. If you don’t need or want more detail than that, then skip to the end of this paragraph. If you’re still reading, I will simply point to other places on the web that you can find out more. HTML uses Cascading Style Sheets (CSS).[6] Recent inventions to reduce the effort for CSS faster tend to interest software developers more than a wider audience, so I will leave out some of the latest front end shortcuts to CSS in this overview. XML also uses style sheets, but the technology is a little different. XML uses eXtensible Stylesheet Language (XSL).[7] JSON, markdown, and asciidoc all use specific applications or general programming languages to get back to another format, such as HTML5, which then uses CSS. Okay, that is enough alphabet soup for now. Let’s look at an example.

The following example is HTML5 markup. The comment line simply states which parts are markup. By the way, HTML5 involves a whole set of technologies that is beyond the scope of introduction.

Unresolved directive in <stdin> - include::example.html[]
  1. HTML5 includes a semantic element called <article>.

  2. The title is indicated by the <h1> tag.

The following is an XML example just to illustrate. XML differs in that you can invent your own tags or elements. See how we have wrapped the content in meaningful elements in items 1-2 below. Callout 3 simply shows a comment line.

Unresolved directive in <stdin> - include::example.xml[]
  1. Semantic container for course.

  2. Semantic container for lesson.

  3. Comment Line is not rendered to the learners.

The following is a JSON (www.json.org) example without the comment (to avoid the debate about whether or not to use comments in JSON for this example).

    "course": {
        "lesson": {
            "title": "This is the title",
            "para": "This is the content."

Okay, that should give you a picture about markup technology.

Now here is the same example in markdown, [8] and asciidoc.[9] Both markdown and asciidoc are also getting popular and can be converted into courseware. Here is an example of markdown, and another of asciidoc.

#This is the title (1)
This is the content.
  1. The title level is indicated by the '#' symbol in markdown.

:lesson: (1)
// Here is a comment (2)
=This is the title (3)
This is the content.
  1. Semantic attribute for lesson.

  2. Comments are allowed in asciidoc.

  3. The title is identified by the '=' symbol in asciidoc.

The similarities between markdown and asciidoc are great if creating low complexity content with paragraphs and lists. Markdown works great for blogging in text and automatically converting to HTML for posting. However, when you have professional level technical documentation requirements, then asciidoc is a stronger solution because it handles more difficult publishing features that markdown cannot.

Notice how little markup exists in the last example of markdown and asciidoc. The ease of asciidoc and markdown is helping their popularity among software developers and others. Markdown continues to spread beyond coders and bloggers because its ecosystem now includes full pipeline tools. For more details, search the web for pandoc,[10] multimarkdown,[11] LaTeX [12] and Apacheā„¢ FOP [13] (Formatting Objects Processor) it is possible to get markdown and asciidoc to HTML or PDF [14] in an automated way, saving time and, therefore, money.

Asciidoc is like markdown because it has minimal syntax compared to HTML5, XML or JSON. It is also exceptionally easy for humans to read. It can be used to automatically and quickly convert text-based content encoded in asciidoc syntax into various formats including, HTML, PDF, ePub,[15] plain text, etc. Because it is free and open source software, using asciidoc can help lower initial costs, and it can help lower recurring labor costs because its automated conversion tool chain reduces cycle time.

If you have people on staff who already have to write code in XSLT,[16] JavaScript,[17] CSS, or other programming languages, they are already familiar with using text editors to edit content, most often on a daily basis.

We have used asciidoc to encode text-based content for fast courseware storyboards. We have used this text-based encoding method for courseware design guides. We have used this text-based encoding for courseware instructor guides and student guides. It works well for technical whitepapers, and we used asciidoc to write this book.

Like more complex XML tool chains such as the Darwin Information Typing Architecture (DITA) [18] XML that IBM originally built and then open sourced, asciidoc lets us break content into smaller chunks for reuse of text-based content components similar to how software developers reuse object-oriented classes between products. Such reuse can save costs and reduce risk.

We can use and reuse text-based content documents rather than what-you-see-is-what-you-get (WYSIWYG), so content can be version controlled in free and open source tools like git,[19] just like text-based software code and included by reference just like software modules/libraries in a software application. This is one of the key benefits of text-based training content.

We have also used XML encoding for various MIL standards, such as S1000D and MIL STD 40051. However, XML encoding requires specialized commercial apps to validate against the schema. These commercial apps can be expensive and complex to initially learn. We have discovered that markdown and asciidoc have lower non-recurring licensing costs, and that both reduce cycle time by reducing complexity, saving labor costs during content creation.

To summarize, using text-based content encoded in

  • markdown - for semantically simple content

  • asciidoc - for semantically complicated and modular content

… allows us low startup costs for experimentation, fast and efficient version control of content, reuse during development and offers a more efficient workflow with a focus on content without constant regard to layout formatting until later in the workflow. These text-based encoding schemes also allow us to build training-related content in a modular way and aggregate into a single large collection or SCORM package and then reuse content using a feature called include. For developers out there, this feature of asciidoc is much like the require statement in ruby programming, the import statement in java programming and the #include statement in C++ programming.

We have found these simple text encoding schemes (markdown and asciidoc) to be faster for content development than HTML or XML directly for the text content. Also, as we have built automatic metric collection and quality assurance checking for courseware, we used the content encoded semantically so that we can algorithmically query the content and compare the actual to the design should.

Text-based encoding of training content also offers buyers that need long shelf-life courseware a way of maintaining source materials over decades without dramatic encoding conversion projects. It also offers buyers the ability to have other contractors/suppliers perform updates and maintenance to courseware made by someone else.

This technology offers many training buyers and producers advantages. This technology is mainstream in other domains. And yet, curiously, it still seems to be leading edge in the training industry. Not many training organizations seem to use it yet. Why this matters:

  • Lean suggests saving transaction costs by using semantic-oriented text markup technology.

  • Lean also suggests that using a modular approach with any semantic-oriented text markup allows us to work on small batches, reducing cycle time.

  • Agile lets us focus on working courseware earlier in the production lifecycle than we did with sequential ADDIE waterfall approaches.

  • Semantic-oriented text markup technology can help the training domain especially for eLearning and performance support efforts.


Line By Line

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

Back to Overview