Technical writers have heard quite a bit recently about Markdown. Putting aside the question of whether Markdown is the right choice for technical documentation, it’s interesting as a tech writer to know more about the language itself. What is Markdown, where can we see it in action, and how can we try it out? Here are some pointers. If you have any other tips or stories about Markdown, I’d love to hear them!
Markdown is a markup language designed for quick and easy creation of simple documents. The syntax is pared down to the minimum, with the result that:
- The syntax is easy to remember.
- A Markdown document is easy to read, since much of the content is free of markup tags.
Along with the markup syntax, Markdown comes with a parser (a piece of software) that converts the markup to HTML, so you can display the document on a web page.
Other well-known markup languages are HTML, XML, reStructuredText, various forms of wiki markup, and many others.
Example of Markdown
Here’s a chunk of the above text in Markdown format, with an added level 2 heading, “What is Markdown?”
## What is Markdown? [Markdown](https://daringfireball.net/projects/markdown/) is a markup language designed for quick and easy creation of simple documents. The syntax is pared down to the minimum, with the result that: * The syntax is easy to remember. * A Markdown document is easy to read, since much of the content is free of markup tags. Along with the markup syntax, Markdown comes with a parser (a piece of software) that converts the markup to HTML, so you can display the document on a web page.
Equivalent in HTML
Here’s the same text in HTML:
<h2>What is Markdown?</h2> <p><a href="https://daringfireball.net/projects/markdown/">Markdown</a> is a markup language designed for quick and easy creation of simple documents. The syntax is pared down to the minimum, with the result that:</p> <ul> <li>The syntax is easy to remember.</li> <li>A Markdown document is easy to read, since much of the content is free of markup tags.</li> </ul> <p>Along with the markup syntax, Markdown comes with a parser (a piece of software) that converts the markup to HTML, so you can display the document on a web page.</p>
Getting started with Markdown
When I first encountered Markdown, I already knew HTML and the wiki markup syntax used in Confluence. For me, the best approach to Markdown was:
- First quickly scan the most basic syntax elements, to get an idea of the philosophy behind Markdown and to pick up the patterns. I’ve included some pointers below, to give you an idea of the patterns in the syntax. Note, though, that there are variations in Markdown syntax.
- Then find a good cheatsheet and refer to it whenever you need to check up on something. Here’s a good cheatsheet.
- If something doesn’t work, consult the full syntax guide.
Where can you try it out?
The best way to learn is to do.
- Grab my Markdown code from above, or write some of your own.
- Paste it into the text box at the top of Dingus.
- Click Convert.
- Scroll down the page to see first the HTML code and then the rendered version (HTML Preview) of your text.
Here are those pointers I promised, to get you started.
# My level 1 heading # Another level 1 heading ## My level 2 heading ### My level 3 heading #### You get the drift
No markup, just an empty line before and after each paragraph.
Put the link text inside square brackets, followed by the URL in round brackets.
Another way of doing links is to define a variable for the URL somewhere on the page, and use that variable instead of the URL in the text. This is useful if you need to use the same URL in more than one place in the document, or if you want to keep the messy, long URL away from the text.
[Markdown] is a markup language, blah blah blah - this is the rest of my page. [Markdown]: https://daringfireball.net/projects/markdown/
* My list item * Another list item * A list item embedded within the previous one * Another embedded item * An item in the main list
There must be an empty line before and after each list, otherwise it gets mixed up with the preceding or following paragraph.
There are a few ways to do numbered lists. Here’s one:
1. My list item 1. Another list item * An embedded bulleted list item * Another embedded item 1. An item in the main list
You can mix and match bulleted and numbered lists, with varying degrees of success.🙂
There’s plenty more you can do with Markdown, and there are a couple of syntax varieties to trap the unwary. For example, GitHub has a special flavour of Markdown.
Recent articles about Markdown
There’s been a fair bit of discussion about the pros and cons of Markdown recently. Here are a few of them:
- Eric Holscher wrote a popular and much commented post in March this year: Why You Shouldn’t Use “Markdown” for Documentation. Congrats Eric, this is a really great example of in depth analysis and reasoned opinion. It also sparked a large amount of impassioned conversation, which is still going on in forums around the world.
- Tom Johnson has a section on Markdown in his course on documenting REST APIS: More about Markdown.
- Victor Zverovich compares Markdown and reStructuredText: reStructuredText vs Markdown for documentation.
- Ben Cotton comparesMarkdown, reStructuredText, DocBook and LaTeX: Markup lowdown: 4 markup languages every team should know.
In my day job, I write docs in both HTML and Markdown. I prefer HTML for comprehensive technical documentation. Markdown is good for very simple documents, but the syntax becomes clumsy for more complex things like tables, anchors, and even images. On the other hand, there are excellent benefits to using Markdown for quick collaboration on a document.
As is so often true, we need to choose the best tool for each use case. It’s a good idea to get to know Markdown, so that you can form an opinion and be able to use it when you need it.
Tech Comm on a Map is ready for 2017! I’ve added a category for “Conferences 2017” and styled it a cool grey. (Grey is THE colour for 2017, right?) The map already has a few events scheduled in 2017. If you know of any more, it’d be great if you’d add them.
Add events, groups, societies, businesses and more
The data on the map is crowd sourced. If you know of an event, a business, or something else related to tech comm, please add it. You can use this online form, or you can use the Android app (see below).
See the map on the web
Grab the Android app
Tech Comm on a Map (Android) is available as an Android app.
The first Write the Docs meetup in Australia is happening soon! I’ll be there, to lead a discussion around working with engineers. Huge thanks to Swapnil Ogale for organising this first meetup ever in Australia.
The session will be in Melbourne at 6pm on Friday, 9 September 2016. Can you come? For more session details and signup, see the Write the Docs Melbourne meetup.
About Write the Docs
Write the Docs (WtD) is an informal community of people interested in technical documentation: technical writers, engineers, UX designers, support engineers, editors, and more. The heart of the community is a series of meetups that happen in various parts of the world. There are also a few annual conferences.
You don’t need to belong to any organisation. Just register for a meetup in your area of the world.
Topic for the Melbourne meetup: Working with Engineers
Swapnil Ogale is the organiser of the Melbourne WtD meetup. He’s invited me to lead the discussion at this first session. We’ll talk about working with engineers. I’ll start with a presentation (about 20 minutes):
How does a technical writer build a super-productive relationship with an engineering team? Sarah has some tips gleaned from working with engineering teams at Atlassian and Google. The tips range from co-location (a fancy word for sitting together) to capitalising on your core skills as technical writer (a sure-fire way of becoming a valued member of the team), and more.
Are engineers keen to update the documentation themselves, and what might prevent them from doing so? See what some engineers replied to these questions.
We’ll close with a group discussion where people can share their own ideas and experiences. If it’s easy, bring your laptop or mobile device along, so that you can contribute to a shared doc.
If you’re an engineer or have another role that touches on technical documentation, come and talk about working with technical writers!
If you can insert the words “by zombies” into a sentence, then that sentence very likely uses the passive voice. A colleague recently reminded me of this tip. It made me laugh, and so I thought it’s worth blogging about. If only to share the chuckle.
Here are some examples of zombie-infested sentences, and their equivalents using active voice.
Geographic requests are indicated by zombies through use of the
coordinatesparameter, indicating the specific locations passed by zombies as latitude/longitude values.
Converting passive voice to active:
You can use the
coordinatesparameter to indicate geographic requests, passing the specific locations as latitude/longitude values.
For an even more concise effect, use the imperative:
coordinatesparameter to indicate geographic requests, passing the specific locations as latitude/longitude values.
Latitude and longitude coordinate strings are defined by zombies as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.
Converting passive to active imperative:
Define latitude and longitude coordinates as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.
Why eliminate the zombie vulnerability?
Active voice is more concise than passive voice. It’s usually easier to understand.
To me, the most important point is that active voice makes it clear who’s responsible for what. Putting zombies aside, if you use the passive voice your readers may think that the nebulous “system” may do the thing you’re talking about.
Who does what, in this example?
The API can return results restricted to a specific type. The restriction is specified using the
Answer: The developer has to specify the types in the
types filter. I don’t think that’s clear, though, when reading the text. Often the context makes it clear, but not always. Zombies lurk in the shadows, ready to grab the unsuspecting reader.
The distinction between active voice and imperative mood
In the above examples I’ve pointed out the difference between active voice and imperative mood. In technical writing, both are good. The imperative mood is particularly concise and clear, but in some cases it can come across as too abrupt.
Should we ever invite zombies in?
I think there are times when passive voice is OK, or even a good thing. Sometimes a sentence sounds artificial if you attempt to inject a subject. Sometimes the passive wording is a well known phrase that readers will accept and understand more easily than the equivalent active phrasing. For example, what do you think of this wording?
These community-supported client libraries are open-sourced under the Apache 2.0 License and are available for download and contributions on GitHub. The libraries are not covered by the standard support agreement.
I’m thinking “documentation” is a misnomer for Stack Overflow’s new feature. “Samples” would better convey the feature’s purpose and form. A topic is basically a code sample (or a few code samples) with metadata (title, tag) and comments.
Calling it “documentation” led me to expect more of it. I looked for such things as navigation aides, a way to order topics in logical sequence rather than by date/popularity, and more control over the hierarchy of concepts.
I love the idea of sample-driven documentation, but I don’t think the Stack Overflow platform offers it yet.
For background, see my earlier posts: What does Stack Overflow’s new documentation feature mean for tech writing? and Information architecture of Stack Overflow’s documentation feature.