Markdown in Technical Writing

Kesi Parker
Jan 18, 2019 · 3 min read

FAQ on Technical Writing

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.

Markdown Preview in Atom

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:

  • Websites

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.

Technical Writing is Easy

Technical writing is for everyone!

Kesi Parker

Written by

Job position: Freelance Technical Writer. I use ClickHelp for technical writing.

Technical Writing is Easy

Technical writing is for everyone!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade