If you’re a software engineer, you’ve probably spent a lot of time refining your environment to boost your productivity. You’ve got your favorite IDE. You’ve got your favorite debugger. You’ve got your favorite performance monitoring tool. But what about your tool for writing documentation, manuals, and reports? After all, writing does take a non-trivial amount of your time, doesn’t it? Indeed, it’s time to get serious about your writing tool.

And let’s remember that you are technical, so WYSIWYG editors may or may not be the best option for you. You don’t necessarily want (or even like!) navigating menus, toolbars, and ribbons to format your text.

So what if, instead, you could easily add all of your formatting styles right into the text as simple inline syntax to yield fully formatted text?

Well, in fact, you can. That’s Markdown and that’s what this tutorial is all about.

When More is Less…

Word processing software is written to satisfy an extremely wide array of users and use cases and, as such, needs to provide all sorts of functionality. But clearly, only a small subset of that functionality is likely to be relevant to each individual user. And for most users, who simply want to author a document (and don’t need to design a marketing brochure or poster), a very small subset of the many, many options available are relevant.

In fact, Microsoft clearly realized this a few years ago when they redesigned the user interface of Microsoft Word into distinct functional groupings that they called “ribbons”. Yet interestingly, most users will tell you that they found the new interface more confusing and difficult to navigate than its predecessor.

learn markdown

Indeed, more can sometimes be less when it comes to ease of use and productivity.

… and When Less is More

Face it, you’re a software engineer, not a graphic designer. You just want to write that manual, or technical document, or report, and be done with it. You’ll be very happy and content with some basic formatting capabilities like headings, bulleted or numbered lists, and code blocks. And, oh yeah, some font formatting (bold, italics, etc.) would be helpful too. That’s about it. (And man, if you could even just do it in vi, that would really be awesome!)

Enter Markdown.

What is Markdown?

John Gruber (with substantial contributions from from technical guru and Internet activist Aaron Swartz) created the Markdown language in 2004 with the goal of enabling people “to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to structurally valid XHTML (or HTML)”.

Markdown was designed to be readable as-is, without looking like it has been marked up with tags or formatting instructions (unlike text formatted with a markup language like RTF or HTML which can be both hard to author and hard to read in its raw format).

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, that can then be converted into structurally valid HTML. So, to be entirely precise, Markdown is really two things:

  1. A plain text formatting syntax
  2. A software tool (the first version of which was written in Perl) that converts the plain text formatting into HTML.

Markdown incorporates a handful of simple, fairly intuitive, and easy-to-use syntax conventions. Especially for you as a software engineer – who is not put off by needing to learn and use these basic syntax conventions – Markdown can indeed be the path of least resistance between what you want to write and getting it written.

markdown syntax conventions

Learn Markdown: Getting Started

Markdown is easy to learn. Super easy. You can learn the basics in five minutes and it will quickly become second nature. And – just like the relationship between CSS and CSS preprocessors – you can use as little or as much as you like.

If you’re used to any kind of plain text writing conventions, then you might already be familiar with some markdown conventions, such as numbers or dashes at the beginning of a sentence to create a list, asterisks around a word for emphasis, and so on. So, for instance, if you want to display something in italics, simply wrap it in asterisks like *this* (as opposed to clunkier HTML syntax like <span style="font-style:italic;">this</span>).

Similarly, you can specify an H1 heading by simply adding a ‘#’ prefix to your line (e.g., # Section Heading, rather than <h1>Section Heading</h1>).

Another great use for learning Markdown, especially for us software engineers, is to use it for documentation on source code repositories. Most repos include a README.md file (.md is the standard extension for a Markdown file). Github, for instance, has its own “Github-flavored Markdown”, which adds additional functionality specifically for development documentation. This can certainly save time over having to write this documentation in HTML.

As a simple example, let’s say you wanted to include the following snippet in your documentation:

Initiating Plugins

Initiate pluginName on your container using jQuery as follows:

$(function() { $('#container').pluginName(); }); Using our container’s ID, we can initiate pluginName with the jQuery method .pluginName().

Here’s a comparison of how this would be done in HTML vs. Markdown:

HTML Markdown
<h1>Initiating Plugins</h1> # Initiating Plugins
<p>Initiate <code>pluginName</code> on your container using jQuery as follows:</p> Initiate `pluginName` on your container using jQuery as follows:
<code>
$(function() { $('#container').pluginName(); });
</code>
`$(function() { $('#container').pluginName(); });`
<p><em>Using our container's ID, we can initiate <code>pluginName</code> with the jQuery method <code>.pluginName()</code></em></p> *Using our container's ID, we can initiate `pluginName` with the jQuery method `.pluginName()`.*

For further help getting started, there are many Markdown tutorials online to help get you up-to-speed including a Markdown overview by John Gruber (Markdown’s creator) as well as an online Markdown tutorial.

Markdown Parsers and Tools

Once you’ve written your article in Markdown, you’ll need a an app to parse the the syntax into HTML. There are a few great ones that are free including:

  • StackEdit - browser-based Markdown editor that has a few sync options with popular services like Google Drive and Dropbox
  • Online Kramdown Editor - another browser-based Markdown editor with an extremely simple interface
  • Mou - the best Mac-based Markdown writer I’ve come across as a geekier option for developers; tons of features and free (while in beta) [this is what I used to write this article]
  • MarkdownPad - great Markdown editor for Windows
  • Texts - a nice cross-platform (Mac and Windows) editor; exports to multiple formats such as PDF, .doc and ePub

Some major platforms have already adopted (or at least allowed) Markdown use in their editors for those who wish to use it. With others, such as WordPress, Evernote, and Google Docs, native support (at the time of writing this article) is not yet baked in, but custom solutions have been introduced by third parties. These include:

  • Popular new blogging platform Ghost, in pursuit of streamlining online writing, uses Markdown for its content editor.
  • For WordPress, the Jetpack plugin now officially supports Markdown, which you can enable under Settings > Discussion if you use the plugin. Or you could use a plugin like WP-Markdown which will convert your post markdown content to HTML, and back to Markdown when you need to edit it.
  • For Evernote, some Markdown apps such as a the online editor Markable or the Mac editor Byword allow export and publishing directly to notes. Or if you prefer to use the Evernote web app directly, you can use a browser extension called Markdown Here which converts a selected note written into Markdown to formatted text with a click of the toolbar button.
  • Google Docs doesn’t natively support Markdown yet, but a few editors (such as StackEdit) will export/sync directly with Drive.

The Downsides

Of course, with great simplicity comes limitations. As I’ve already explained, Markdown was not written for complex word processing tasks requiring advanced formatting features. If that’s what you need, Markdown is not the right tool.

But for developers who need to write a user manual or technical documentation or a technical report, Markdown provides a near-perfect balance between simplicity and the features that you need.

Perhaps the biggest drawback – especially for us engineers who are change control junkies – is the inability to work collaboratively in Markdown and to track changes (one notable exception to this, though, is the StackEdit plugin for Google Docs). And of course, with a minimal amount of effort, one can simply collaborate on a Markdown doc via a git repository and thereby get all the change tracking and collaboration that one typically needs.

Conclusion

So is learning Markdown for everyone? Of course not. No one tool ever is.

But if you’re a software engineer, it could very well be precisely the writing tool you’ve been looking for. So if you haven’t given it a try yet, you really should take it for a spin.

About the author

Storm Farrell, South Africa
member since February 1, 2015
Storm is a front-end developer with a focus on static modular frameworks, JavaScript-powered interactivity, and intuitive content management. He’s worked frequently with WordPress and collaborated, worked remotely, and led development on some fairly large jobs. He firmly believes that his code is his creative output for expressing his abilities, and he measures his value based on the impact he can have on the client’s business. [click to continue...]
Hiring? Meet the Top 10 Freelance Web Developers for Hire in December 2016

Comments

Evan Wieland
Great intro for new users! Good work Storm.
Evan Wieland
Great illustrations also Luboš, if you made these.
Luboš Volkov
I had a pleasure to collaborate on these with https://dribbble.com/zamax he made them awesome! :)
Pedro Victor Pontes Pinheiro
I don't have a favorite performance monitoring tool... Any suggestions for php and/or java?
Soonts
Markdown suits well for small pieces of text on the internets. However, a document that is longer than two pages usually contain table of contents, page numbering, tables, text wrapped around images, footnotes, and many other things. Spelling and grammar checking helps as well. I believe every programmer must be able to use MS Office to some extent. The software is de-facto industrial standard. Memorizing that bold is Ctrl+b, italic is Ctrl+i, and hyperlink is ctrl+k is no harder than learning markdown. BTW, most keyboard shortcuts are here from at least Office 2000, being unaffected by that GUI redesign of 2007.
Evan Wieland
Gustavo has some talent for sure! Especially when it comes to drawing mustard and melted cheese :)
Tomislav Crnicki
"this< /style >" should be "this< /span >"
Demir Selmanovic
Thanks, fixed
Storm
Thanks! Thanks to Hyam too for helping me polish it off.
Zachary Blackwood
A very simple tool for converting MarkDown to nice-looking HTML (using Bootstrap formatting, etc.) is http://strapdownjs.com/. Though it appears to no longer be actively developed, it's a very handy tool as is.
ANONIMBUSZKULCS
Did you read the article? If you need TOC and other fancy stuff, Markdown is not for you. But if you ever want to add a README.md to a github repo, I bet Markdown is more than perfect than that monstrous MS Office pack. (And not to mention that it is much more easier to track changes, as Markdown is a plain text format)
Soonts
Yes, I have read the article. No, the article does not say that. Instead, it suggests markdown as a replacement for MS Word. It even discusses how cluttered the author thinks the Word UI is. About tracking changes — if you need that, Word has “Track Changes” feature for decades. I think this topic is a good example of the law of the instrument. If the only tool you have is a plain text editor, then it is tempting to treat everything as if it were a source code. While this approach might work in some cases, using a specialized tool to author documents — like Word or OpenOffice Writer — is usually more efficient.
ANONIMBUSZKULCS
Probably we are not grinding in the same mill :-) You are talking about tracking changes within MS Office, while I talking about change tracking in a version control system. Anyways, you are right, if somebody wants to create a full fledged documentation, then MS Office and alternatives are more vital. But, my experience converges to that plain text is much suitable for a developers.
Soonts
I am a full-time software developer for almost 15 years. No thank you, plain text is not suitable for me, as I strongly prefer MS Word. Besides, not everyone is a developer. There are also QA personnel, managers, designers, and many other people. They all can read documentation regardless of the source format, but for them, well-composed documentation is a sign of professionalism. I am sure most of those people can use MS Word to some extent, but do not know markdown — so they can only edit a document if it is written in Word. If you work in science, the format everyone can read and write is TeX. In business however, such universally acceptable format is MS Office. Instead of making everyone learn markdown it will be much easier if you just learn to use Word.
ANONIMBUSZKULCS
What should I say? I am too a full time software engineer for more than 15 years, and I do not want to push you to use Markdown - that is not for you, because your environment does not accept it (and probably, you are very comfortable to use MS Office). But in these days there is a new generation of software developer community, which uses and produces new style free stuffs (for example AngularJS, Node.js, github, etc, etc). They are trend makers. Lot of large software development companies started to use their stuff, and you hardly find any .docx file in those releases. So, I think (again) you are right if we talking about business related environment, but it fails on the new style environment. (and just for the record: currently I am working in a business environment, where I receive .docx files from Q/A, but in my spare time, I am involved in open source stuffs)
Rishat Muhametshin
Thanks for referencing Mou. Despite the status of this product is unclear, it seems a great tool to edit Markdown and, well, see what you get in real time (mediated WYSIWYG).
Joe C
I decided to try Stack Edits and Texts. Thank you for the write up and recommendation.
Storm
Isn't what you're suggesting exactly the same? Everyone who uses GUI word processors is essentially forced to learn to use tools like MS Word. But what if that wasn't the norm? I don't say anything about making everyone learn markdown. In my conclusion, it specifically says that Markdown is not for everyone, and that if you're a software engineer, you should at least give it a spin. Even creative writers should. And while yes, I do use MS Word as an example of what I think is wrong with writing tools, it is intended to be an introduction article to entice people who have not yet really tried it out.
Storm
Nice! Thanks for the recommendation.
Soonts
“But what if that wasn't the norm?” — non-GUI word processors already were norm for very long time, from 1970s to late-1980s. They didn’t speak markdown, but they featured something similar, e.g. take a look at this screenshot: http://upload.wikimedia.org/wikipedia/en/e/e3/Wordstar_Screenshot.png Users switched to GUI editors as soon as PCs became powerful enough to run them. “if you're a software engineer, you should at least give it a spin” — just because it’s new and it’s open is not enough for me. I need some real advantages, at least for some tasks. But I don’t see any. “Even creative writers should.” — creative writers need e.g. word count feature. They also need the best spelling and grammar checking tools available. Also they can’t: editors and publishers don’t want markdown, they want .docx. Or if they’re academic publishers, they want LaTeX.
philippe99
I'm a full software engineer since 25 years. I daily use Markdown (+ PDF export) for making small notes/reports. For more complicated documents (with TOC, ..) or for sales who can't imagine that there are other ways to write texts except MSWord, I use the MSOffice suite. In my company, I daily fight for "the content is more important that the container" and MD is just in this area: you just focused on typing words, not "presenting" words. MarkdownPad on WIN, nvAlt+Marked on Mac.
Flavio Escobar
I have been using Markdown without knowing its existence. It's really easy!
comments powered by Disqus
Subscribe
The #1 Blog for Engineers
Get the latest content first.
No spam. Just great engineering and design posts.
The #1 Blog for Engineers
Get the latest content first.
Thank you for subscribing!
You can edit your subscription preferences here.
Trending articles
Relevant technologies
About the author
Storm Farrell
HTML5 Developer
Storm is a front-end developer with a focus on static modular frameworks, JavaScript-powered interactivity, and intuitive content management. He’s worked frequently with WordPress and collaborated, worked remotely, and led development on some fairly large jobs. He firmly believes that his code is his creative output for expressing his abilities, and he measures his value based on the impact he can have on the client’s business.