How to get started with Markdown and where to try it out

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.

1. Grab my Markdown code from above, or write some of your own.
2. Paste it into the text box at the top of Dingus.
3. Click Convert.
4. Scroll down the page to see first the HTML code and then the rendered version (HTML Preview) of your text.

Basic syntax

Here are those pointers I promised, to get you started.

Heading levels

# My level 1 heading
# Another level 1 heading
## My level 2 heading
### My level 3 heading
#### You get the drift

Paragraphs

No markup, just an empty line before and after each paragraph.

Links

Put the link text inside square brackets, followed by the URL in round brackets.

[Link text](https://my.site.net/path/)

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/

Bulleted list

* 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.

Numbered list

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. 🙂

More markup

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.

My opinion

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.

Advertisements

Mozilla Popcorn Maker and a tour of the Confluence documentation

Mozilla’s Popcorn Maker is pretty neat. You can grab a video and augment it with clickable text boxes. You can also add other interactive widgets, such as a live Twitter stream or a fully-functioning map from Google Maps. I’ve been playing with Popcorn Maker for a couple of weeks, and I thought other people may like to have a go. So I’ve put together a video for you to mess up… hrrm… review. It’s cunningly disguised as a tour of the Atlassian Confluence documentation. But actually, it’s a bit of fun. 😉

Popcorn Maker is all online. There’s nothing to download. You give it the URL of a video from YouTube or another supported location, then drag and drop events onto the video. The Popcorn Maker editing environment adds a timeline, a bit like the one you see in a Flash editor, but driven entirely by Javascript, HTML, and CSS. You also get a library of widgets to add and configure, such as text boxes, popups, maps, Twitter streams, and so on.

Jumping right in

Are you keen to try Popcorn Maker? Try making a remix of my Popcorn Maker movie, “Popping the Confluence docs“. I’d love it if you’d add a comment on this blog post with a link to your remix!

Making the video itself

I used Screencast-O-Matic to record the movie itself. It’s a great tool too. Just like Popcorn Maker, everything is online. You do need to install Java on your computer, and it’s handy to have a webcam for the audio part of the movie. Other than that, all you need is your connection to the Internet. You can use Screencast-O-Matic free of charge, if you’re happy to have a watermark at the bottom of your movie.

Once I’d made the movie, I uploaded it to YouTube and then used Popcorn Maker to annotate it and make it available for remixing.

Some thoughts on Popcorn Maker

It’s pretty cool to be able to grab a video from YouTube (or Vimeo, Soundcloud, or an HTML 5 video) and add bits to it online, all within your web browser. Nifty technology!

But I think the huge potential lies in the fact that anyone can remix the videos. Just grab a movie that someone else has created, and decorate it yourself.

This has very interesting possibilities for collaborative development of “how to” videos. Another use that springs to mind: The review of videos. Instead of writing separate notes, people can paste their comments directly onto the relevant spot in the video. And they don’t need specialised tools to do it.

The icons and styling in general could do with some tender loving care from an artist or designer.

The integration with Twitter, Flickr and Google Maps is awesome! It makes me wonder what other integrations would be useful. Perhaps a HipChat room. Or an RSS feed from WordPress?

I’d also love to see some way of finding and sharing remixes of a given video. Ha ha, searching for “Popcorn remixes” brings up a number of song remixes!

References

• A Mozilla blog post introducing the Popcorn Maker technology: Introducing Popcorn Maker
• The main Popcorn Maker site: https://popcorn.webmaker.org/
• A Popcorn Maker tutorial
• An article from PCWorld: New Mozilla tool lets anyone create and hack interactive videos
• An article from Co.Design: Popcorn Maker: A Dead-Simple Drag-and-Drop App For Remixing Web Videos
• A list of Popcorn Maker projects
• Screencast-O-Matic, an online tool for recording screencasts: http://www.screencast-o-matic.com/
• The video on YouTube, without the Popcorn Maker annotations: Confluence Documentation Tour
• “Popping the Confluence docs” – a Popcorn Maker movie for you to remix to your heart’s content. 🙂

STC Summit day 2 – Using DITA

I’m at STC 2012, the annual conference of the Society for Technical Communication. This post contains my notes from a session called “Using DITA”, by Michael Priestley, lead DITA architect at IBM.

Michael started off by telling us what DITA is and giving us some historical background.

What is DITA and who is using it?

DITA (Darwin Information Typing Architecture) is an open standard for designing, creating and publishing modular information, such as technical publications, help sets and websites. The standard is owned by OASIS. It was originally created for technical communication, but was designed to be more broadly applicable. We are starting to see other types of content adopt the DITA standard now too, such as learning and training. As a result, some LMS systems are now adapting to support DITA too.

The latest DITA standard, OASIS DITA 1.2, was approved in December 2010.

A public survey at ditawriter.com conducted a survey and found that around 250 companies have posted public case studies. Breaking the usage down by industry sector, around 30% of companies that use DITA are in the software sector. Geographically, the largest number of DITA users is in North America, followed by Europe.

In technical communication, a survey in 2008 found that DITA was the most popular standard, at 35%.

Michael discussed some case studies from around 2008-9,including the reasons why the companies adopted DITA :

• Avaya adopted DITA to solve problems of low-quality for globalised content, inconsistency in content and style, and problems in training new writers. They reported improvements in these areas, as well as increased user satisfaction and happier writers,
• CaridianBCT adopted DITA to reduce translation costs. They reported savings of $100,000 in the first year.
• Medtronic needed to improve productivity. The metrics quoted were based on the amount of content that the team managed to produce using the new reuse model.
• WebSphere adopted DITA for content reuse in the documentation for their application server product. They report 80% reuse of their content across the entire set. Note that the percentage of reuse required depends on the amount of commonality across the different products.

Smart content

Michael discussed a study by the Gilbane Group, called “Smart Content in the Enterprise”. One of the most interesting aspects was a shift from an inward-facing to an outward-facing view of the content. Focus on what the users need from the content, and on delivery as the starting point of design.

The core elements are providing metadata, integrating social systems with the content, and using structured content as the source.

Getting practical – DITA topics and maps

DITA is all about chunks of content called topics. This concept has nothing to do with reuse. It’s all about content use. With all types of content other than novels, people jump in and out of a book or manual to find what they need. They don’t read the book from start to finish. What we must do is understand what the user needs to do, and prioritise that over the needs of the product.

Here Michael took us through the core elements of DITA:

• The high-level structure of a topic in DITA.
• An example of a DITA map. A map does all the referencing and organising. You would have a map per output format.
• A map in topic links.
• A map with generated navigation and links. The build process takes the information in the map, and turns it into a table of contents and supported linking patterns.

Conditional processing

Michael showed us the underlying DITA tags for conditional processing. We don’t assert that you should include or exclude something. Instead, we assert that it applies to a specific product or products.

Then you set conditions as part of the build process, to include or exclude products, or to flag specific content.

Conref

In some cases, you want to reuse a fragment of a topic or a fragment of a map. In those cases, you would use a conref.

A conref is basically an empty element that instructs the build process to pull in the content from another element at publication time.

Note that you should do this as little as possible. In most cases, you would use conditional processing to include or exclude a topic. Reason: If people change a paragraph, it could mess up your content reuse. Topics are a more basic unit of structure, and so are less subject to breaking changes.

Information typing

The idea is that different types of information are best served by different structures. What’s more if a particular type of information is presented in a particular structure, that will help the user understand the information.

DITA defines a specific set of structures for tasks. For example

• Prerequisites
• Steps
• Warnings

Each of the above elements has sub-elements, and rules about what can go where. The task  is a type of topic. You can use a task anywhere that you would use a topic. The task has rules unique to it. We call this “specialisation”.

What’s new in DITA 1.2?

• Taxonomies. Michael showed us the big vision of how his team uses taxonomies to provide progressive disclosure from the product UI to the web-based user assistance.
• Learning and training specialisations.

What’s coming in DITA1.3?

The group is working to provide a lighter-weight DITA editing experience, for technical communicators and other DITA users too.

Michael’s presentation style is easy and authoritative. Thank you Michael for an informative insight into DITA.

STC Summit day 1 – Getting started with HTML5

I’m attending STC 2012, the annual conference of the Society for Technical Communication. Monday afternoon started with a presentation by Peter Lubbers, called “The future is landing: Getting started with HTML5″.

Peter’s presentation covered these points:

• HTML5 – what and why
• HTML5 features
• Toolkit

The world is moving to HTML5. Peter thinks the impact on the world will be even bigger than what DITA has been to tech comm.

HTML5 will not replace DITA. We will probably continue to author in DITA. The two are complementary, especially with respect to the semantic markup.

What is HTML5?

• HTML5 is the new major milestone for HTML. It includes things that have earlier been separate specifications, such as JavaScript APIs.
• The focus is very much on webapps, and creating webapps that are on a par with desktop applications. One of the components that eventually merged into the HTL5 spec was originally called Web App 1.0.
• It represents an explosion of growth in many different areas.

Why should we care?

• New features that “pave the cow path”. For example, new features in web forms.
• A simplified Doctype. Just “HTML”.
• Simplified character set in the meta tag.
• Simplified markup. You can create a minimal document in just 70 characters! The browser will supply the fill-in elements.
• HTML5 is universal, works in all world languages, and is designed for accessibility- semantic markup and WebVTT (format (Web Video Text Tracks) is a format intended for marking up external text track resources).
• You need fewer plugins.
• HTML5 is designed to be secure.

Next Peter took us through the new HTML5 elements. The new tags are semantic – making a first class element out of attributes that people commonly used, such as a figcaption element for image captions. One of the benefits of semantic markup is making the document machine readable.

Some elements gave also been declared obsolete, such as frames, framesets and inline styling.

Peter recommends the HTML5 Doctor site.

There is a lot of new functionality around web forms. For example, in a signup form you can specificy a “placeholder” attribute containing text that appears in an input field before the user has entered anything. (It typically appears in grey text, and disappears as soon as you click in the field.) You can also add an attribute that makes a field mandatory. Field types are useful for specifying dates, colour pickers, and so on.

CSS3 is part of HTML5, and defines a number of new features, such as rounded corners, transitions, web fonts.

Media queries are very important, especially when you talk about responsive web design. See the website The Boston Globe as an example. You can drag the browser window, and change its size, and it remains looking good. You can define the way the page should look, and the columns that should appear, based on the width and height of the window.

In the area of audio and video, HTML5 supports a number of media formats and gives you a simple way of including them. There are some hiccoughs with browser supports and codecs, but basically it works.

Peter recommends the Miro video converter for converting movie files to different formats for browser compatibility.

For graphics and 3D figures, Peter talked about two types of graphics API:

• Canvas – HTML5 has a “canvas” element. You can think of it as a programmable bitmap, where you have complete control over every pixel.
• SVG. Not new, but HTML5 now has native support for scalable graphics. One of the great libraries for SVG is D3, an open source project that you can roll into your own projects.

For a cool experience on an iPhone, try the Kaazing racer. The car responds to changes in the position and orientation of the phone. This is based on the device specification in HTML5, and also on the new web sockets technology.

One feature that will affect technical communication is the ability to make documents available offline. If you add the necessary elements to your HTML, the browser will cache the pages and make them available offline, at the same URL.

Toolkit:

• Authoring tools, such as MadCap Flare, support HTML5.
• Modern browsers support many of the features. See the HTML5 test page to check the overall compabitility ofour browser. And see When can I use… to check specific HTML features. For mobile browsers, see Mobile HTML5.
• PageSpeed is a great tool for analysing the speed of your page and telling you what to do to fix the performance. It’s an add-on that you need to install.
• For getting started, Peter recommends HTML5 Boilerplate, which includes a complete set of templates for a web page. It includes years of learning about best practices.
• Modernizr gives you a library of feature support detection. It will pull in extra code for browsers that do not support the feature. Also HTML5 Cross Browser Polyfills.
• There are also a number of mobile emulators that help you develop HTML5 pages for mobile devices.

Above are the notes that I took during Peter’s presentation. There was a lot more that I didn’t have time to capture. Peter has posted his slides on SlideShare. Thank you to Peter for a very interesting presentation, full of useful tips.

Writing a book with DocBook and a Confluence wiki

We’re in the final stages before sending my book off to the printers. Exciting! While we wait, let me tell you a bit about how the publishing team and I have produced the book. We’re using a Confluence wiki and DocBook XML.

Here’s our process in brief:

• Plan, write and review the book on a Confluence site.
• Use the Scroll Wiki DocBook Exporter to convert the content to DocBook XML.
• Use DocBook XSL-FO style sheets to create a PDF file for sending to the printers.
• Use XSL to generate ebook formats too.

This post is about writing and reviewing the book on the wiki, and converting the Confluence content to DocBook XML – the first two points in the list above. Richard Hamilton, at XML Press, is the expert on the further DocBook processing.

A bit about the book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Details are at XML Press. It is all about developing technical documentation on a wiki, with a focus on Confluence wiki. And just to be ultra meta, I’ve written the book on a Confluence site. Dogfooding FTW!

Writing, planning and technical review on the wiki

Richard Hamilton and I have spent the last nine months on a Confluence wiki site. We kicked off our planning there in May 2011. Since then, I’ve spent around 400 hours writing the content on the wiki. Ryan Maddox, our illustrator, has uploaded his images onto the wiki. For two weeks in early December, the technical reviewers joined us there too – six knowledgeable and enthusiastic people:

• Alan J. Porter – Writer, speaker, consultant
• Anne Gentle – Technical writer for OpenStack
• Ellen Feaheny – CEO of AppFusions
• Mark Fidelman – Social business GM at harmon.ie
• Robert Rhyne Armstrong – Director of documentation for RouteMatch Inc
• Sherif Mansour – Technical product manager at Atlassian

The wiki was abuzz with review comments, opinions and counter-opinions, laughter and chat.

Now it’s gone a bit quiet while Richard and I work on the last stages of book production. When we launch the book, we’ll open up the wiki site too. You’ll be able to join us there and make it buzz again. 🙂

DocBook for the publication processes

DocBook is an XML standard for documents, developed by O’Reilly as a means of making their publishing process more efficient. It is now an open standard maintained by OASIS.  Richard Hamilton, at XML Press, uses DocBook XML to publish a range of books on the subject of technical communication. Using a customised set of the open source XSL style sheets for DocBook,  Richard can create HTML, PDF (through XSL-FO), EPUB and other epublishing formats from the DocBook source.

Converting content from Confluence wiki to DocBook XML

So, I’ve finished writing the book and the reviewers have worked their magic too. It’s all on a Confluence wiki. The content is stored in the Confluence database in wiki format. How do we get it to DocBook so that Richard can create the print and ebook formats?

Enter the Scroll Wiki DocBook Exporter.

Scroll Wiki DocBook Exporter is a plugin for Confluence, developed by K15t Software. (A plugin is a small piece of software that extends the functionality of the wiki. It is similar to an add-on for a web browser.) Once you have installed the Scroll Wiki DocBook Exporter on your Confluence site, you can export a page, a set of pages or an entire space, to DocBook XML.

How to use the Scroll Wiki DocBook Exporter

The first thing is to add the plugin to your Confluence site. You need to be a Confluence system administrator, then you can install the plugin in the usual way:

1. Log in as a Confluence system administrator.
2. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
3. Type “scroll wiki docbook exporter” into the search box and click “Search”.
4. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
5. Click “Install Now”.

See the Confluence documentation on installing plugins.

You will need a license key from K15t Software. They provide a free evaluation license that gives you full functionality for 30 days.

Once the plugin is installed, a new option appears in the Confluence “Tools” menu, allowing you to export the content to DocBook format.

1. Go to the page that you want to export. If you want to export a set of pages, go to the parent page of the set.
2. Click “Tools” > “Export to DocBook”.
3. Adjust the options in the dialog that pops up:

Scroll Wiki DocBook Exporter

When you are ready, click “Start Export”. The plugin will create a zipped file containing the DocBook XML and attachments, and will offer the file to you for downloading.

A sample of the output

Here is one of the book’s pages on the wiki:

Front page of the book on the wiki

And here is an extract of the DocBook XML:

<?xml version=”1.0″ encoding=”UTF-8″?>
<book xmlns=”http://docbook.org/ns/docbook&#8221; xmlns:xlink=”http://www.w3.org/1999/xlink&#8221; xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance&#8221; xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd&#8221; version=”5.0″ xml:id=”scroll-bookmark-1″>
<info>
<title>Confluence, Tech Comm, Chocolate</title>
</info>
<part xml:id=”scroll-bookmark-2″>
<title>Confluence, Tech Comm, Chocolate</title>
<chapter xml:id=”scroll-bookmark-3″>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
</chapter>
</part>

[SNIP]

<index />
</book>

Index, footnotes and figure captions

The Scroll Wiki DocBook Exporter supports these too. The plugin adds a number of macros to Confluence, which you can use to mark up the index entries, footnotes and figure captions. I’ll write another post with the details. I’m sure many people are agog to know how this works. 😉

Working with K15t Software and XML Press

Richard and I have worked on this project with Tobias Anstett and the rest of the team K15t Software.  They are great people to work with: knowledgeable, enthusiastic and energetic. As far as I know, this is the first time anyone has written a book on Confluence for publication via DocBook XML. We have added new functionality to the plugin, especially for the index and footnotes, adapting and tuning as we go.

Thank you all. It’s exciting to help perfect a plugin that many other authors and technical writers will be able to use.

And I can’t wait to get my hands on a copy of the book!