In my post called Diagrams in Documentation (Markdown Guide) I told how to create diagrams using Markdown. However, do you really need to use Markdown for technical writing? Let’s figure out.
What is Markdown?
Markdown was created by John Gruber in 2004 to enable people “to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML)”. So, Markdown is a lightweight markup language using plain text formatting syntax.
Markdown is not so easy as Microsoft Word, where you just click buttons to format words and text in general. Markdown is like HTML — you need to indicate which words and phrases should look different, but Markdown is easier than HTML. For example, to create paragraphs, use a blank line to separate one or more lines of the text. You should not indent paragraphs with spaces or tabs.
Here is Markdown Basic Syntax, so you can make sure how Markdown is easy.
In order to use Markdown, you should download Atom. It’s available for many platforms.
Moreover, if you don’t want to install anything, you can use Markdown in online Markdown editors like Dillinger. Just open the site and start typing in the left pane. A preview of the rendered document appears in the right pane.
Do technical writers need Markdown?
According to Markdown documentation, this markup language is good for:
But is it really good for technical writers? Nowadays, many tech writers have their blog, for example, here is my blog called Technical Writing is Easy. Also, I always follow ClickHelp Technical Writing Blog, and sometimes write guest posts there. So, any technical writer can use Markdown for their websites and blogs. For example, it’s easy to use Markdown for Medium, here is a tool that makes it easy to go from Markdown to a Medium post. So, your post formatting will be saved and represented in a Medium post.
How does Markdown work in documentation? To work with Markdown, create a file with .Markdown or .md extension. Write your text as you usually do it but using Markdown syntax. Then save your file and, if your tool supports Markdown, import it.
Of course, Markdown is great because it’s easy but there are also many cons to use it for writing technical documentation, for example, Markdown doesn’t have any kind of semantic meaning, you can’t add a Warning or a Class, you can only write text.
I think it’s better to use a professional online documentation tool with WYSIWYG editor where you just click buttons to format your text, and there is no need to learn all the Markdown syntax.
What is your experience with Markdown? Do you use it for writing technical documentation?
How did I become a technical writer? What skills do you need? Read FAQ on Technical Writing.