The Ins and Outs of Using Markdown for Technical Writing
Friday October 12, 2018 , 9 min Read
Many technical writers either currently use or are interested in using Markdown to write their technical documentation. It’s a bit like Marmite – some people love it and other people kind of hate it.
Markdown generates some controversy, but it still proves incredibly useful in certain contexts. In this post, we’ll discuss exactly what Markdown is, and whether it’s appropriate for your documentation project.
Definition of Markdown
John Gruber is the original creator of Markdown, and he defines it as:
“Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).”
MarkDown
Gruber’s definition shows that Markdown is intended for anyone producing content on the web – which nowadays could be pretty much anyone. Markdown is open source free software, which means that anyone can use it.
It’s licensed under a BSD-style open source license.
What is Markdown Editor?
The first thing you really need to know about Markdown is that it’s a way of formatting text content in an editor – without requiring you to know or use coding languages like HTML or CSS. You certainly don’t need to know some other programming language such as JavaScript or Ruby.o
What is MarkDown Editor?
Syntax
For our purposes, Markdown is “plain text formatting syntax” – but it’s also a tool (parser) that converts this plain text formatting into HTML to display on the web.
The Markdown syntax is the information that your tool holds about the text. So for example, presentational syntax tells you how to present the text, as in the case of making it bold or underlined. Semantic syntax tells you what the text actually is, so that could be a list or a reference.
Markdown is fairly notable in that it combines both presentational and semantic syntax.
How to use Markdown for Technical Writing?
The key way you work with Markdown is in a file with an extension that is either .Markdown or .md. You write your text in the normal way, but format it using Markdown syntax – which can be found online.
You save your files in the Markdown format if you’re working in a plain text editor, or ensure your editor has a parser for Markdown. Many editors support Markdown, like Document360 which is our knowledge base platform. If a product supports Markdown, the company will tell you somewhere on their features page or their homepage.
Just try using a bit of Markdown in Trello to format some of your cards. It presents a vast improvement over no formatting and is relatively easy to do.
This is an excellent cheat sheet for getting started with Markdown. Check out this in-depth guide to Markdown from Ghost.
Markdown Versus Other Markup Languages
Markdown is just one kind of markup language, of which there are many. The name “Markdown” is in fact a play on words of the term “markup”.
Markdown is used to render plain text in the browser but other markup languages may communicate directly with the computer. XML (Extensible Markup Language) is both human and machine-readable.
According to Webopedia, a markup language is defined as a tool used for:
“The processing, definition and presentation of text. The language specifies code for formatting, both the layout and style, within a text file. The code used to specify the formatting are called tags.
“HTML is a an example of a widely known and used markup language.”
This means that the tags for formatting are directly applied within the plain text file, as opposed to being specified in a separate file like CSS for example.
HTML stands for Hypertext Markup Language, and probably the best-known markup language used on the web today. Markdown has evolved as a way to simplify markup for web users.
History of Markdown Editor
History
Markdown was first created in 2004 by John Gruber, who collaborated with Aaron Schwartz on the syntax.
The reason they began their project is because historical markup languages were not at all easy for the average person to use.
The term “markup language” originated in the traditional publishing industry, where documents would be literally “marked up” by the author or editor. This was to tell the printer how to format the document when printing the final copy.
Imagine you had to write something, but also needed to communicate systematically to other people down the production line that you want:
- This bit in bold
- This bit to be a heading
- This should be a quote from another author
- Tell them an image is to go here
- This whole section highlighted
Enter Markup Languages
Since most markup languages were originally designed for very complex technical projects, there grew a need for a “lightweight” markup language. It had to be so simple that just anyone could use it – without years of training.
Technical Writer Tony Ibbs delivered a very interesting talk at Write the Docs Prague 2018 about the history of markup languages.
Markup Language
As you can see from Tony’s slide, Markdown is still a bit of a newcomer on the markup language scene.
Benefits of Markdown for Technical Writing
Benefits
As a result of its simplicity, Markdown quickly became very popular among web writers.
Interestingly, it experienced a surge in popularity among technical writers around 2016. Some people were very excited about Markdown, while others – not so much.
Many technical writers find lots of benefits in using Markdown for their documentation. Some of these benefits are:
- Markdown provides semantic meaning for content in a relatively simple way
- You can write rich formatted content extremely quickly (compared to writing directly in HTML tags)
- You can read Markdown easily in plain text before it is rendered later by HTML
- It doesn’t interrupt your workflow with the need to click buttons
- It’s platform-agnostic so your content is not tied to the format of your editor
Markdown is also lightweight, which means you don’t have to learn a lot to get started with it.
Lots of product documentation is written in Markdown because it is so versatile, and it can usually be transferred between different platforms. For example, you can write in Markdown in a text editor like Atom, or even a version-control platform such as GitHub since that also supports Markdown.
Markdown can be used in Static Site Generators such as Jekyll or Hugo, which are tools specifically designed to be documentation sites.
It also works in our own knowledge base software, Document360, which allows you to work in Markdown in the editor and provides shortcuts for writing in Markdown.
Document360
{Image caption: Our Document360 editor with Markdown capabilities enabled and Markdown shortcuts}
When Should you Use Markdown?
So why should you use Markdown instead of a WYSIWYG editor, which are standard and abundant nowadays?
The answer is that a WYSIWYG editor usually requires you to click buttons to achieve the formatting you want, and you are limited by the design of the software creators. You also have to work in your chosen editor at all times, which takes the focus away from the actual content.
Some people are concerned that Markdown doesn’t have enough functionality to suit their needs or if they extend it then the content won’t be reusable. Markdown can be extended with extra functionality. This means someone creates another version (or “flavour”) of Markdown to suit their needs. On the other hand, if you extend it, your Markdown flavour may not be portable to another platform.
Ask yourself whether you are likely to have thousands of pages content to be potentially reused across multiple platforms such as web, internal knowledge base, and print?
In this case, Markdown probably isn’t for you.
But if you want to quickly create simple text documentation with rich formatting, then Markdown may be for you.
Controversy Surrounding Markdown
Markdown was created for a reason, but some people are strongly against using it. Reasons for this include:
- Markdown is not originally intended for writing documentation so there may be limitations in how you can use it (John Gruber himself is a prominent blogger, and blogging is one of the best use cases for Markdown)
- It’s not standardised like other markup languages, so you don’t necessarily know how it will be rendered in a browser
- There are dozens of “flavours” of Markdown as people have extended Markdown to offer the functionality they need, which aren’t compatible with one another
- Markdown merges the semantic meaning of your text and how it should be displayed, which some people find unsuitable
- It’s limited stylistically in how you can display your content – but this is an intentional design choice behind Markdown
Markdown’s innate flexibility and potential for use in a wide variety of contexts is what has led some to warn against using Markdown. Many people recommend it, but it just isn’t suitable for everyone.
The co-founder of Write the Docs community Eric Holscher advocates strongly against the use of Markdown in technical documentation.
He recommends to use Asciidoctor, or Sphinx and reStructuredText (rST). rST is another markup language like Markdown but it has an official standard, which makes it popular among some developers.
Should I Use Markdown Editor?
undefined
Just like anything, Markdown is a good choice if your project needs are suited to it. Markdown has limited functionality because of the way it was designed. This makes some people swear by it and some people hate it.
Think about the interface in which your content is being created, the technical complexity of your documentation project, and the types of users who will need to create and review documentation.
Make sure you design the proper workflow for your documentation, and research the proper technical writing tools for delivery to avoid future styling issues. Markdown is not an editor in itself, so it has to be coupled with a CMS (Content Management System) to produce live documentation.
If you want to extend your Markdown-formatted documentation with CSS or more HTML, it’s important to note that these extensions will stop the style of your content being portable between systems. Some things you have added to work in your current editor (eg Document360 being one editor) may not port well, and therefore not work in a different editor.
It’s probably safe to say that many of the problems people using Markdown come from using it in inappropriate contexts. Markdown is safe to use if you know exactly what it can do, and what its limitations are.
Final Remarks
Markdown is a great tool for easily making formatted text files that display across a variety of platforms. It’s popular with technical writers for its ease of use and relatively short learning curve.
Research your options before committing to launching a product documentation project in a particular format like Markdown. Make sure the other platforms you need to use – now and potentially in the future – are Markdown-compatible.
If you’re ready to go with Markdown, get started with Document360 now.
