7 thoughts on “Why we need constrainable lightweight markup languages”

  1. Mark, it’s impressive that you’re creating your own lightweight markup language, one that fits well into your SPFE architecture. But will you get enough traction with the language to make it appealing for widespread adoption? Will it only work with SPFE? If so, aren’t you asking authors to make a pretty big step of confidence into your tooling world?

    Maybe SAM will take off and become popular, and maybe tool vendors will start to support it. But I think it’s hard to create that kind of momentum. This is why I tend to piggyback onto existing platforms and work within their “constraints.”

    Re Markdown, I wouldn’t consider my position to be “MarkDown is as good as anything for tech docs.” I would say that although many tech writers think you need XML to do more robust, sophisticated authoring, you can actually do robust, sophisticated authoring when you combine Markdown with Liquid, HTML, and Jekyll. But I do recognize and admit that Markdown with its various flavors can be frustrating.

    I would agree that if you just stuck with authoring in Markdown alone, it’s too constraining/limiting. But there’s an easy way to extend Markdown through include templates in Jekyll. I currently do this for images, notes, and other features. But links are still the weak point. (Maybe I’ll elaborate briefly on this in a post.)

    At any rate, I agree about finding the right balance between constraints and options, and what you say about XML being too general when the audience is too large seems spot on. I glanced through some of the SAM files in your github project to get a sense of the syntax, constraints, and other features you’re writing about.

    My initial, quick gut reaction is that I’m in awe of your ambitiousness and the thoroughness in which you’ve approach the problem, but I’m wondering if the syntax is going to be too complicated for mainstream adoption (though maybe that’s not a concern). Markdown’s popularity is mainly due to its simplicity and the fact that so many platforms parse it and transform it in cool ways.

  2. Thanks for the comment Tom.

    Will SAM get traction? I don’t know. All the ones that did get traction started with the same question. It is the same problem every new proposal faces, and, of course, most proposals don’t get much traction.

    I think new systems arise one of two ways. One is an industry consortium is formed to address as shared problem. The other is that one person just gets sick of the available tools and decides they would rather invent something they like better. Markdown certainly is in the latter category, just as XML is in the former.

    The industry sponsored initiative have the advantage that they have a substantial built in audience and the disadvantage that they are the product of a committee and thus usually overly complex and difficult. The products of individuals have the advantage of lightness and fitness for purpose, and the disadvantage of no built in audience.

    So I recognize both SPFE and SAM as labors of love — or perhaps labours of frustration. If they catch on, wonderful. If they don’t, I can live with that too. I enjoyed creating them, and learned a lot from the process. My book and series on structured writing would not be possible without what I learned from developing both of them. And when they are done, I will be happier working with them than with other tools.

    If others find the same pleasure and utility in them, that’s icing on the cake.

    The syntax is one of the most interesting design issues of SAM. It is more complex than Markdown, but considerably less complex than ASCIIDoc or reStructuredText (at least to my eye). More specifically, it relies less on the use of non-standard punctuation, which I find distracting in those languages. The added complexity is because it needs named blocks and annotations, which Markdown does not have. I tried to design the syntax, and its shortcuts, to feel natural and intuitive, but that is difficult to judge. The formal specification, though, requires a lot of detail to spell out what all the shortcuts do. It is really hard to judge ease of use for something you have invented yourself. What works for me may work for millions or for no one else. In particular, the use of indentation to define structure (a la Python) is something I find really intuitive but others may balk at. Time alone will tell.

    Thanks for nuancing my statement of your views on Markdown. I knew I was probably stating that with too broad a brush, but trying to nuance it myself seem like a sidetrack. The beauty of blogging is that we get to nuance these things in the comments.

    It is the combination of pieces that is really interesting about your solution. Lots of systems (like DITA) end up embedding what are essentially programming languages in their markup (not Turing complete, by any means, but imperative none the less, and capable of interesting and problematic side effects). Your approach is much more up front about doing that, and I suspect it is the more robust for it.

    My preference, though, is for purely declarative content, or as close as I can get to it. This means a more complex tool chain (or at least one with more steps) and more case-specific markup languages, but the gain in ease of authoring, audit capability, and future proofing is worth it in my view.

    1. Thanks for writing this up, Tom. For comparison, here is what your include example would look like in SAM.

                  $stuff=ice cream 
                  Here is some >($stuff).
                 $stuff = special text

      ~~~(#some) is a fragment definition. The fragment defines a variable $stuff and uses it in the text of the fragment.

      (~some) inserts the fragment. By itself, this would insert “Here is some ice cream”, but with the redefinition of $stuff, it outputs “Here is some special text”.

      This mechanism is not tied to a file insert instruction. Insertion of files is treated separately. But the fragment could be defined in a separate file and brought in by inclusion.

      More generally, what you are doing, essentially, is reproducing the source/template structure that we find in all structured writing. It is formalized in the XML world in the XML/XSLT pairing.

      The crucial question in the design is what goes in the source and what goes in the template. The more complexity you can factor out of the source into the template, the easier authoring becomes.

      The key to making it easier to use is to factor it so that the source is declarative and the template is imperative. That is, all the commands are in the templates; all the declarations about the text are in the source. Thus you have a purely declarative source that is easy for people to write.

      This business of factoring things out of the source and into the template is the essence of what I am describing in my series on structured writing on TechWhirl. http://techwhirl.com/series/structured-writing/

Leave a Reply

Your email address will not be published. Required fields are marked *