Check out Ed Marsh's podcast, and also My New series: Jekyll versus DITA

by Tom Johnson on Mar 23, 2015
categories: dita • jekyll

In case you haven't already discovered it, there's a great new podcast in the tech comm field called Content Content, by Ed Marsh.

So far Ed has recorded two episodes, each about an hour long. Ed follows an easy-going interview format, and he does an excellent job in bringing out the best in his show's participants.

In episode one, Ed interviews Sharon Burton, and they talk at length about the customer experience. I enjoyed getting to know Sharon better through this episode -- she really has a lot of passion, and it was interesting to hear how her background in anthropology, studying people, carries over to her work in tech comm.

In episode two, Ed interviews Alan Houser about his experience with the STC and about structured authoring and DITA.

I listened to both podcasts and enjoyed them greatly. I have always been curious about why there aren't more podcasts in our field, and I'm excited to listen to upcoming episodes. My only criticism is that waiting one month between episodes is simply too long. C'mon Ed, can't you squeeze in another podcast more frequently? :)

Actually, the monthly pace is probably a good strategy to avoid burnout and "podfading," as they call it. I know that with my podcast, I go in spurts. But just listening to Ed makes me eager to set up some more podcasts with people. There's nothing better than listening to someone insightful talk about a topic so relevant and applicable to my work.

Alan's mixed feelings about DITA

If you want to listen to episode two and jump straight into the structured authoring and DITA content, go to about the 30 minute mark. Here Alan gets into a fascinating discussion in which he shares his mixed feelings about DITA.

Ultimately, having been on the DITA OASIS committee, Alan is a proponent of XML. But he also admits that he is the DITA consultant who often doesn't recommend DITA. He says that for certain situations, DITA can be a grand slam home run. And in other situations, DITA can be an absolute fiasco.

I love that someone can be so practical and objective in evaluating solutions. In fact, I once discovered an interesting presentation by Alan on Slideshare called What they won't tell you about DITA. Love the title -- and the content doesn't disappoint.

During the podcast episode, Alan and Ed mentioned some of my recent posts about turning away from DITA to explore static site generators that process Markdown instead of XML.

Ed noted that it's hard to use an authoring syntax that doesn't accommodate more robust publishing scenarios. If you're limited to Markdown, there's simply a lot you can't do. This makes it difficult to do single sourcing, content re-use, multi-channel publishing, and so on.

Ed noted that he recently turned to DITA, and while he finds the architecture complex (he's at the level where he's creating his own XSLT stylesheets to do imports from Confluence), he is also enamored of the slick, efficient publishing capabilities of DITA.

Overall, I liked the discussion and wished I could have injected a few points. I decided to start a series on my blog comparing Jekyll with DITA, in part because I have just done two pilots using both systems, and because I also find it a fascinating subject that is highly relevant to our field.

Upcoming Berkeley presentation

This series of posts (Jekyll versus DITA) will culminate in an upcoming presentation that I'm giving at the Berkeley STC chapter on May 13. Here's the title and description of that upcoming presentation:

Jekyll versus DITA: Bridging the Gap between Tech Comm and the Web

Although the web continues to burst at the seams with innovation after innovation, the technology of tech comm tends to evolve in an independent sphere, changing at its own sluggish pace. Is the divide between web tools and tech comm tools a rift that can be bridged any time soon? Or is tech comm, because of its needs for content re-use, conditional filtering, and multi-channel outputs, destined to maintain its own independent track indefinitely?

The interesting thing about innovation is that, although developing technologies underperform mainstream technologies as they evolve, eventually their trajectory overtakes the mainstream technology. Think of examples with Netflix and Blockbuster, Wikipedia and Encyclopedia Britannica, or even reaching farther back, with the telephone and the telegraph.

The same story may take place with static site generators on the web, such as Jekyll. These platforms, originally designed as blogging tools for hackers, have the potential to let technical writers -- particularly those working in developer documentation spaces -- create flexible, user-friendly websites for tech comm publishing. In fact, most of what you can do with DITA, you can also do with Jekyll.

In this presentation, I'll first provide a context for innovation and describe the divide between web and tech comm tools. I'll then demonstrate how Jekyll, a static site generator, works. Finally, I'll compare the major features of DITA against Jekyll and evaluate the two models.

Some disclaimers

Let me put a few disclaimers here up front about this series. First, I vow to be objective as possible. While I admit an inherent bias for web publishing tools (I was, after all, a WordPress consultant for a number of years), I want to avoid distorting the facts.

Second, it's important to acknowledge that some features are more important to some companies than others. The importance of certain features has to be considered when doing any kind of comparison.

Finally, recognize that static site generators are relatively new on the scene and as such, fit into the "developing technology" category that currently underperforms mainstream technology. Developing technologies only become disruptive when they mature enough to overtake the mainstream technology.

That's enough for the introduction. Now let's get into some real comparisons.

Next: 1.1 Authoring with Markdown in Jekyll versus Authoring with DITA in OxygenXML