The glass slipper that fits when it’s perfect and doesn’t when it’s forced.
Markdown is huge right now. It’s not new, but it has experienced a meteoric rise in popularity recently. Founded by John Gruber and Aaron Swartz in 2004, Markdown is a text-to-HTML conversion tool.The goal of Markdown was to create something that has a less intense cognitive admission price than some other markup languages. Let’s take a brief foray into Markdown and what it’s all about.
What’s the Point of Markdown?
Markdown’s inception was centered around building a plain text format that was both easily readable and usable. The idea was to provide a markup language that enabled software professionals to create web-ready content faster and more fluidly than before. The readability of Markdown helps vastly with this. Rather than a library of tags like HTML or XML, Markdown uses a smaller collection of punctuation based tags. Markdown “tagging” while writing content is much less disruptive to a content developer’s ability to read, write, and edit on the fly. It’s an open standard, too, so it’s not locked into any proprietary format and works with any plain text editor, making it usable just about anywhere. Its formatting is similar to that of any familiar word processor, think MS Word, Google Docs, and the like, so it isn’t a completely new User Interface to get used to. It’s not very difficult to write, even less difficult to read. Heck, I wrote this article in Markdown. So, what’s the deal? Here comes the but.
Applying Markdown Properly
You’ve probably used Markdown or a variance of markdown at one point or another. Given its widespread use and the diversity of its applications, there stand to be some things it’s better at handling and others that it’s not. Let’s determine a few of them. This way, you can make Markdown an ally without making it responsible for bearing burdens beyond its strength.
When Markdown Works Best
Because of its accessibility and relative ease of use, it has several applications that you can apply almost immediately. It’s fabulous and beautifully effective for things like:
- Blogging
- Book writing
- Note-taking
- Basic web content
- Certain aspects of documentation
I say certain aspects of documentation because Markdown is a common documentation go-to for developers, which is great for smaller, one-off projects. Writing a piece of software that only requires a readme is perfect for documenting in Markdown. However, where Markdown’s effectiveness begins to wane is when documentation needs to scale into something larger. We take Markdown and a few other common Documentation standards and compare them extensively against each other in an aptly named article that puts you in the decision making seat: What Is the Best Standard for Documentation?
When Markdown Should Take the Backseat
When it comes to managing enterprise levels of public-facing documentation that need to be actively monitored, Markdown breaks down pretty quickly. It lacks a structured reuse mechanism. This, in turn, prevents consistent updates to large bodies of content simultaneously. It’s also not built to deploy to multiple different outputs in a single publishing instance. Markdown is designed for text-to-HTML, remember. Other outputs require individual formatting and adjusting just to publish. This is too much work when your organization needs to quickly send content to several different output formats.Finally, there’s the part about metadata. I’ve said it once, and I’ll say it thrice more: if your content is hard to locate, it’s not very useful. Complex, semantic metadata tagging helps us find content easier. I mentioned earlier that I was writing this in Markdown. Here’s the syntax in Markdown for the H2 at the beginning of this section: ## Applying Markdown ProperlyNow, here it is in HTML: <h2>Applying Markdown Properly</h2> Where Markdown is easier to read and write, HTML is capable of adding semantic tags to the H2 element that clearly define it. Look again: <h2=”markdownProperly”>Applying Markdown Properly</h2>Where I’m able to apply the ID markdownProperly to clearly denote what that H2 tag is in the HTML, Markdown has only a limited ID feature that serves as little more than formatting syntax. And that’s a simple example among numerous ID signifiers in HTML. With huge bodies of content, semantic metadata tagging is vital to organizing, finding, and managing your content.
Markdown & DITA Together?
Yes, this can be done. It’s important to leave each standard to its strengths. DITA has the content management capabilities to support massive libraries of content that need to be written, changed, and deployed at scale to several outputs. Combining DITA XML’s structure and semantic power with the authoring ease of Markdown could very well be a dynamic duo in documentation. We just need to leave each respective documentation standard to its strengths.If you don’t believe it just reading it here, check our Co-Founder’s presentation on the topic: DITA and Markdown: Living in Harmony.
