Docs is code

Clint Hocking's birthday blog post led me to look at the EXP tabletop roleplaying game, and in turn, that got me looking at AsciiDoc and the Docs as Code movement. I understand completely the arguments that AsciiDoc makes against Markdown. Regular readers will recall that I experimented with converting my course plans to GitHub-hosted Markdown and almost immediately backed away from it: Markdown almost immediately requires a polyglot approach for anything significant. However, I don't see AsciiDoc nor Docs as Code as addressing what I consider the most important tool for technical writing: the ability to embed scripts.

I have been using lit-html for years (and Polymer before that). What it lets me do is separate the structure of my writing from its display. For example, when I write an assignment for my students, I might conceive of it as having a list of objectives. In Markdown, AsciiDoc, or even HTML, I could easily represent that information as an ordered or unordered list. Later, however, I might decide to change the representation, instead showing it as a definition list, or making sure the name of the objective is bold, or generating unique links to each individual objective. In any of those plain markup environments, I have to do this by hand or, worse, with a regular expression.

What I don't see from Docs as Code, although I admit I haven't done more than a cursory search through their materials, is the observation that docs is code. If I separate my model and my view, I gain a robustness that any journeyman programmer understands. For example, using lit-html, I can create a simple JavaScript data structure that represents a goal, with a name and a description. Either or both of these can be html templates, not just strings. With that structure defined, I can create a list of them for an assignment. Now, on my first pass, I show them as list by iterating through the list and dropping the data into list items in an ordered list. When my requirements change—as they always do—I can modify my script and make the same data into a definition list, section headings, etc. If I need to change the actual definition of an assignment goal, I can make that change explicit.

Of course, the whole thing is in version control with sensible commit messages.

I have taken a similar approach in the past to build documents using LaTeX, coordinating the execution of multiple scripts through GNU Make. That works when LaTeX is needed for document output, but it feels less elegant to me than being able to generate the HTML directly from the Javascript.

If you know of an approach in the AsciiDocs or Markdown vein that gives the same level of robustness as what I can do with lit-html, please let me know.