Exploring Markdown in Collaborative Authoring to Publishing Workflows

by Tom Johnson on Jun 4, 2013
categories: technical-writing

One of the pains in tech comm is figuring out a good collaborative authoring to publishing workflow.

When you're authoring content, you're usually in the figure-it-out mode. You add pieces here and there as you learn how a system works. You gather feedback from subject matter experts, who also add comments, delete or add content, and so forth as they review the content.

Sometimes the content originates from the subject matter expert and you're the one editing the content. Regardless, during this development phase, content is in a constant flux — increasing in words, decreasing in words, changing shape and form with each iteration. Sections get added and deleted. Steps are constantly altered, rearranged, inserted and reordered, and so on.

During content development, I need a format that's flexible and easy to work with. I also need the content on a web platform that's easy to share access so that I can collaborate with others.

I've found that Google Docs works great for collaborative authoring. Subject matter experts can highlight a word and add comments in the sidebar. Their comments appear right next to the highlighted words. I can also reply to their comments or resolve them. Resolved comments are hidden in an archive that I can always open and view later. Subject matter experts also find no problem at all originating new content in Google Docs.

Best of all, Google Docs is free. SMEs don't need to download special software or pay extra fees to access, write, and edit content.

Wikis are also good content development tools. Although sometimes adding comments in a system like Mediawiki isn't quite as intuitive (there's a separate tab on each page for comments), the wiki format has proven useful across the web for collaborative content needs of large-scale teams.

The Problem

Here's the problem. When I'm done authoring the content, I want to port the content into another system for publishing. In my case, Drupal. Others have different publishing needs. Maybe you have a company website where the help material goes, or a help center portal, or some other platform. How do you get your content out of one system and into another, especially when that first system is the easygoing collaborative scratchpad that doesn't have a lot of structure to pull on intelligently?

If you try a copy-and-paste route with Google Docs, you end up with a ton of span tags and other inline formatting in your code. Every paragraph has a left-to-right class associated with it. The HTML export from Confluence can be problematic as well. It all depends just how much your authors have been using those rich text editor buttons. The more they use rich text editing, the worse the code looks.

What I need is a universal format that allows content to be transported from one system to another without any reformatting.

The need for porting content from one system to another was exactly why I was looking into DITA, because you can do this kind of system porting with DITA. But all the workflows seemed problematic. If I authored in an XML editor and output to HTML, and then copied and pasted the HTML output into Google Docs, I'd still be spending a lot of time tagging content, because the source in Google Docs would change as the content gets edited and updated by SMEs and other authors. I'd have to copy and paste the Google Doc content back into my XML editor and restructure everything with the right tags.

Vendor-provided collaborative platforms for structured content offer solutions to this problem but usually recreate the collaborative tools within their own system. And these online platforms aren't cheap, especially if you have a lot of users.

What I want is a lightweight system for porting content around. In my brief exploration into feasible and inexpensive methods, I stumbled across Markdown. Markdown is a shorthand syntax for HTML. It's pretty similar to Mediawiki syntax but simpler, and its main job is to transform the syntax to HTML.

But here's the cool thing about Markdown: the syntax is readable in its syntactical form. Writers and editors can easily work with the content without having to render it to the HTML format to read it in a more practical way.

When I say readable, here are a few examples:

Heading 2
========

Heading 3
--------------

A numbered list:

1. first item
2. this is my second item
3. this is my third item.

A bulleted list:

* first item
* second item
* third item

A code example:
~~~~~~~
<?php echo <p>Hello World</p>; ?>
~~~~~~~

And so on. You can read it pretty easily even though it's in a code-like syntax. In contrast, the same content in a markup language is going to be much more cumbersome to read through. The same content in HTML would look like this:

<h2>Heading 2</h2>
<h3>Heading 3</h3>

<p>A numbered list:</p>
<ol>
<li>This is my first item.</li>
<li>This is my second item.</li>
<li>This is my third item.</li>
</ol>

<p>A bulleted list.</p>
<ul>
<li>This is my first item.</li>
<li>This is my second item.</li>
<li>This is my third item.</li>
</ol>

<p>A code example:</p>

<pre>
<?php echo <p>Hello World</p>; ?>
</pre>

What's neat is that you can still write Markdown in Google Docs. Just leave that rich text editor alone. Google Docs won't render the Markdown into HTML or anything. If it did, that would be wonderful. But it doesn't.

The question is whether Markdown is sufficiently readable for SMEs who have no knowledge of Markdown syntax to quickly understand and work in Markdown syntax, rather than resorting to the rich text editor. Time will tell on that one -- I haven't yet piloted this little Markdown experiment.

Lots of people on the web, however, have been using Markdown for years (especially programmers). For example, if you don't use Google Docs, you could also use Markdown with Mediawiki. The Alternate Syntax Parser Extension converts the Mediawiki syntax to Markdown syntax.

And Drupal has a Markdown filter module that allows you to use Markdown instead of HTML as the syntax.

What does this mean? Whether you're authoring content in Google Docs, Mediawiki, Drupal, WordPress, or some other platform where Markdown is supported, you can simply copy and paste the content from one web platform to another without reformatting it. Markdown is a common language among platforms.

Granted, copy and paste kind of sucks a best practice, but it beats reformatting the content by hand.

Also, this authoring to publishing workflow would by no means fit a large publishing house's need, such as publishing a 200 page manual or handling translation. But if you're in an agile environment, where you're publishing only a handful of new articles a week to an existing web platform (which you keep adding and adding to), it just might be enough structure to simplify the authoring to publishing workflow.