1. Introduction
  2. More is less …
  3. Les is more …
  4. What is Markdown
  5. How to learn Markdown?
  6. Tools and markdown parsers

Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor. As the initial description of Markdown contained ambiguities and unanswered questions, many implementations and extensions of Markdown appeared over the years to answer these issues.1

Introduction

As a software engineer you have spend a lot of time preparing your programming environment to boost productivity. But what about writing documentation, manual, some short tutorials or even reports? These tasks sometimes non trivial amount of time.

Sometimes WYSIWYG is not enough especially when you are technical/engineer. This kind of editors may not be the best option for you, for example: maybe you don’t like menus, toolbars, clickable options. And at this moment you can use markdown as a simple tool to create your documentation.

More is less …

For example Word as a tool is written to satisfy a wide group of users. Provide all sorts of functionalities. But let by honest, only a small number of functions are used by individual users. Microsoft realizes this a few years ago when they redesign the user interface by grouping functionalities into ribbons. But moues of users will tell that they found the new interface more confusing than before. More can be sometimes less when it comes to being productive.

Less is more …

Most engineers are not graphic designers. If you want to write documentation, manual, or report you can skip graphical nice fishers. For most people some basic formatting, ok maybe some font formatting would be helpful. And of course, if you can do it in vim …. ;)

What is Markdown

John Gruber2 created the Markdown language in 2004 in collaboration with Aaron Swartz3 on the syntax, 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 allow to write easy to read/easy to write plain text format, that can be converted into valid HTML. But markdown is really two things: plain tezxt formatting syntax and software tool, which convert plain text into HTML.

Markdown can indeed be the path of least resistance between what you want to write and getting it written.

How to learn Markdown?

Markdown is super easy to learn. 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 have 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. 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>)

When you want to specify an H1 heading, you can add # prefix to your line: # Section Heading:

<h1>Section Heading</h1>

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 is another great use for learning Markdown, especially for us software engineers.

Tools and markdown parsers

  • Strapdown.js - Strapdown.js makes it embarrassingly simple to create elegant Markdown documents. No server-side compilation required. Use it to quickly document your projects, create tutorials, home pages, etc.

  • Text - cross-platform (Mac and Windows) editor; exports to multiple formats such as PDF, .doc and ePub.

  • MarkdownPad - MarkdownPad’s only requirement is the Microsoft .NET Framework 4 Client Profile, which will be automatically installed if you don’t already have it. MarkdownPad is compatible with Windows XP, Windows Vista, Windows 7, and Windows 8.

  • Mou - is a Markdown editor for developers, on Mac OS X. Features live preview, sync scroll, auto save, powerful actions, auto pair, custom themes and CSS, HTML and PDF export, enhanced CJK support and more.

  • Online Kramdown Editor - browser-based Markdown editor with an extremely simple interface

  • StackEdit - StackEdit provides very handy formatting buttons and shortcuts, thanks to PageDown, the WYSIWYG-style Markdown editor used by Stack Overflow.

There is also a few popular platforms like: WordPress, Evernote, GoogleDocs that already adopted Markdown use in those editors. But there is also a limitation. 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.

For people who need to write a user manual or technical documentation, Markdown is a perfect balance between simplicity and the features that users need. But of course, there are people who can’t imagine that there are other ways to write text except for MS Word. There can be also a daily fight about what is content more important than presenting words.

Reference:

  1. Daring Fireball
  2. Markdown tutorial
  3. Markable.in
  4. Byword
  5. Markdown here

My site is free of ads and trackers. Was this post helpful to you? Why not BuyMeACoffee

Annotations:

  1. Definition from Wikipedia, the free encyclopedia. ↩

  2. John Gruber (born 1973) is a writer, blog publisher, UI designer, and the inventor of the Markdown publishing format. ↩

  3. Aaron Hillel Swartz was an American computer programmer, entrepreneur, writer, political organizer, and Internet hacktivist. He was involved in the development of the web feed format RSS and the Markdown publishing format, the organization Creative Commons, the website framework web.py, and the social news site Reddit, in which he became a partner after its merger with his company, Infogami. ↩