Does Markdown fit into your content strategy?
Markdown is a text-based markup language designed for content authoring. Using a limited set of formatting marks, you can create content and render it to HTML or another format.
There’s a growing buzz about Markdown in the technical communication community. While great for quick content development, there are some limitations to its usefulness.
Some unitaskers – like Markdown – do one job very well, and can be applied to other similar tasks. But if you also need cake… [image: flickr/jamiesrabbits, cropped]
In a lot of ways, Markdown reminds me of a stripped-down Microsoft Word. (Hear me out…)
Word is great for quick content creation and has one primary target in mind: print. Now, you can create online content in Word, but it requires some additional scripting (now mostly behind the scenes). But to start doing more interesting things with your Word content, you need to add additional functionality using either a plugin or a third-party application.
The same is true with Markdown. Many of the Markdown extensions involve scripting—often within the content files—and still target a single primary output. And since there is no single Markdown standard, some third-party applications even use varying or proprietary markup.
If you are looking for a quick and easy content solution for a very specific need, by all means use Markdown. But if you have complicated content requirements, you may be better off looking at something more robust.
And there’s no reason why you couldn’t allow some contributors to use Markdown to jot down initial drafts. But those drafts need to be converted, consumed, and then managed in your main source format. That is, Markdown would be a disposable starting point.
Markdown is neither intrinsically good nor bad. It has real use cases, but its returns diminish as content needs grow. While it may be a “unitasker,” it does its job well.
About the author
Larry Kollar
“All those variants” turns out to be not so big a deal. The only time it would become a problem is if you’re sharing raw Markdown (your variant) with some other group (their variant). Commonmark (commonmark.org) is a good choice if that’s an issue.
It’s more likely, though, that you would be sharing the HTML output instead. All the variants I’ve tried (personally, I think MultiMarkdown is a good choice for technical writing) generate the cleanest HTML I’ve ever seen that wasn’t written by hand. My fiction-writing workflow uses Markdown -> HTML. From there, I can feed the same HTML to an EPUB formatter, or run it through an XSL:FO script I wrote to format a PDF. It takes less than half an hour to produce publish-ready copy.
But I digress. For technical writers, I know two scenarios where Markdown really works:
1) You’re working in a sprint-based development environment, where you need to get it done fast. Bonus points if the engineers are feeding you raw copy in Markdown already.
2) You have to do some of your work on mobile devices. Few if any mobile apps support XML or even HTML, but all you need is something that can edit raw text. There are mobile apps like Byword that are Markdown-centric.
Lightweight DITA includes Markdown as an input format, and (as you probably know) DITA-OT 3.0 supports it. I see exciting times ahead.
Bill Swallow
Hi Larry,
All very true. But I still think Markdown will be a disposable source format, even in the context of Lightweight DITA. Markdown just isn’t contextually rich enough on its own, and isn’t built for robust reuse.
What you get is M > LwDITA, not M <> LwDITA. That is, LwDITA is the master, maintained source. M just feeds new content into it.
Further, LwDITA may be fine for some needs, but it’s still not contextually rich enough to handle more robust publishing requirements.
Larry Kollar
Maybe. I’m writing a smallish (maybe 50 topics when complete) book in LwDITA as a personal exercise, and so far I haven’t felt the need to uplift any of the topics out of MDITA. Yet. Granted, I’m using a bookmap to organize the thing, Still, the beauty of LwDITA is the ability to match the format of each individual topic to the required complexity.
I’m not ignorant of the power (or the drawbacks) of an XML=based publishing system. At work, I’m ankle-deep head-first in the muck of a DITA conversion, and spearheading several of the sub-projects including the plugin and file conversion. Over the last few years, I’ve gone from being a lone writer in one part of a medium-sized company to being part of a global team, and the entire company is still trying to adjust to the new mindset.
I first heard about LwDITA in April, at the CIDM conference in San Diego. If DITA-OT 3.0 had been available then, I probably could have made a case to use LwDITA to ease us into the transition (especially since I wrote a transform to pull Author-It XML into Markdown + ditamaps). Lately, I’ve been thinking about writing a transform to turn OPML outlines into bookmaps. Dare me, and I’ll do it. Throw in a craft beer, and I’ll throw in reltables. 🙂