Reviewing content in DITA versus Jekyll

by Tom Johnson on Apr 13, 2015
categories: dita • jekyll • blogging • findability • java • javascript

This is another post in my series comparing DITA against Jekyll. In this post, I want to compare reviewing methods for the two systems.

Theoretically, you could review content from both systems in the same way. But you could also take very different approaches to reviewing content as well.

How to review content in Jekyll

This review method isn't specific to Jekyll but rather one that is sometimes used in Github projects. Derwood Kirkwood explains this method in a comment on Neal Kaplan's ever-popular post, The Death of Technical Writing:

I have of late been required to produce documentation using GitHub's documentation support features -- GitHub is more than just code management, it is a platform to support workflows for development teams. In terms of documentation, documents are treated just like source code — they are authored in markup (I am no fan of markup), and stored and managed in a repository — either with code or in repos just for the docs.

Updates/additions are done via branching, just like code. ... there is a workflow called fork/pull request -- content submitters (be they developers, writers, or other "members of the crowd") fork a document repository -- meaning a contributor has a complete copy of the repo's content that can be updated in any way the contributor likes.

When the contributor wants the updates reviewed, a "pull request" is submitted. A pull request alerts the people named on the request that updates are available for review on GitHub. When one reviews updates to such a request, GitHub has a feature that allows one to make comments directly in the document -- the feature has a diff capability, so you can see what the update was compared to original, so a comment can be placed right where the update was -- or anywhere else in the doc. Others, including the author, can comment on the comments, so it becomes like a conversation over changes. (You can see how this tool facilitates crowd-sourced authoring.)

The end result of this process is that, once approved by content owner, the update is finally merged into the project repository and becomes part of the "official documentation base.”

Check out GitHub and see if it works for you.

4/14/2015 update: See this excellent post by Anne Gentle called Git and GitHub for open source documentation for a more in-depth exploration of how to use revision control software like Git and Github to do documentation reviews. In particular, watch the following video:

Although I'm all for treating documentation as code, I've never been involved in a Github workflow like this, and honestly I'm skeptical that it would work for heavy content reviews where you have a lot of annotations, questions, and other back-and-forth comments.

I also can't imagine checking in changes, creating pull requests, and comparing diffs from multiple reviewers. (Maybe comparing diffs among collaborators, but not reviewers.) Maybe I just need to experience the process to believe it. When I'm really comfortable with revision control, and I'm working with other reviewers who are equally comfortable with revision control, maybe.

Instead of using this pull request method, I recently experimented with a Markdown collaboration/review platform called Beegit. I really like Beegit. It's a new product and many features are still forthcoming, such as the ability to bulk import and export content as separate files. But at least I can paste in my Markdown/HTML source into Beegit and copy it when I want to paste it back into my source, and I don't experience any alteration in formatting (no extra spaces, no munged apostrophes, nothing to adjust).

The review aspects in Beegit work very similarly to Google Docs, in that you can make comments in the margins, reply to comments, and resolve comments. Beegit isn't free, but so far it has worked pretty well for conducting reviews.

Nevertheless, there are problems in reviewing Jekyll content. When I have Jekyll content that is sourced from includes, data files, or has other sophisticated formatting going on, this is lost in the Beegit interface. In these situations, the reviewer has to compare the source against the output to see what's really going on (including viewing screenshots).

My main issue with Beegit is the inability to bulk import dozens of topics cleanly in and out. (This feature is on the roadmap, though, so maybe soon we'll see it?) I did the old copy-and-paste routine for a while before deciding it was too inefficient.

One major upside of writing primarily in Markdown is that reviewers can see and read the source even with the raw syntax. With DITA, reading through the content when you're viewing the source is more difficult due to all the tags.

You could really use any collaborative platform to paste in Markdown content, such as Google Docs. When I worked at Badgeville, we reviewed documentation using Google Docs. Because everyone was on the Google Drive platform (instead of MS Office), this review method worked extremely well. It was also easy to paste the content in and out of Google Docs and keep the Markdown formatting.

At my current company, Google Docs is discouraged, so I've been looking at other options. Additionally, at Badgeville I only reviewed content that I was preparing for each release (about 5-10 pages every two weeks), whereas now I'm working on a 1.0 product, so the documentation is hundreds of pages.

Comments in margins or at the page's bottom

What's better -- commenting in the margins or commenting at the page's bottom?

Even though annotations are helpful because they put the comment right next to the relevant content, they're problematic when you start to edit that content. As soon as you erase the paragraph with the annotation, the margin-comment disappears. At least when the comment is at the bottom of the page it tends to remain.

It would be ideal if users could comment in the margins of the published site itself, but the only way to really do that is through browser extensions that create little sticky notes or other markers. Then the browser extension feels like spam when you aren't reviewing anything.

You could use Disqus or another commenting service to add a comment form below the topic. This would probably work well if your content is public and you're allowed to use third-party systems to handle reviews.

Discourse is an attractive open source alternative, but installing it seems a bear, requiring quite a few utilities that I've never worked with (Postgres, Redis, Ruby, Docker). Still, it seems the best option if you want to avoid the third-party commenting services and you have a static site.

How to review content in DITA

I've talked about how to review draft DITA content before, and I don't want to retread old ground. There isn't a rock-solid way to review content for any system, whether from DITA or some other help authoring tool.

With DITA content, I've tried using DITA-content imported into WordPress (then used WordPress's commenting features), I've used Oxygen's commenting feature with their webhelp output, and I've had people just respond to me via email excerpting passages. All of these methods worked pretty well.

In general, I try to avoid PDFs for review. If you send out a PDF, people can annotate in the margins, but they don't see other people's comments. As a result, you have the same people providing the same feedback. Ideally, as comments trickle in, you want to update the source so that other reviewers don't waste their time relaying the same feedback.

Additionally, if you update the source, the only way to let reviewers know about the update is by sending out a new PDF for them to review.

Even so, the PDF can easily be printed and marked up, so if you have a short review period, this approach might work well.

Best method for review

I'm still hoping to find the best method for review. Ideally, here's what I want. I would like Google Docs to offer a source-only mode that doesn't apply any formatting and which also provides Markdown syntax highlighting. Then I want to port content in and out using a bulk import/export.

Stackedit.io might be a tool that can facilitate that, but I haven't quite figured out how to SSH content in and out of that system (Dropbox, Google, CouchDB, etc. aren't options available to me.)

Conclusion

Because Markdown is readable even in its source form, it seems to offer a lot of potential for reviewing systems. However, there aren't many reviewing tools built to insert comments into Markdown sources. There are a few other tools similar to Beegit (Penflip, Draftin), but none really compelling.

One editor I found that I really like is Ulysses for Mac. It does provide a beautiful comment feature as well as probably one of the best Markdown editors, but again, no bulk import/export as single files back in to my Jekyll project folder, which is where all the magic happens.

Next: 1.6 Producing PDFs in DITA versus Jekyll