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.
Download the eBook of this article to understand “The Ins and Outs of Using Markdown for Technical Writing” offline!
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).”
Gruber’s definition shows that Markdown is intended for anyone producing content on the web – which nowadays is pretty much for 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.
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 te # xt 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 its features page or its 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.
Also, Check out: Must Attend Technical Writing Conferences of 2024
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 is called tags.
“HTML 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 is probably the best-known markup language used on the web today. Markdown has evolved as a way to simplify markup for web users.
Simple and easy-to-use Markdown editor to format text content without the need for HTML or CSS.
History of Markdown Editor
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 are 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
Markup the content in the traditional way but visualize the look and feel of content in a modern style.
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.
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
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 rendered 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.
The 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.
{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 is standard and abundant nowadays?
Click here to read more on The Ins and Outs of Using Markdown for Technical Writing