Skip to main content
May 15, 2013

Structured authoring AND the web

We read Tom Johnson’s post on Structured authoring versus the web with some dismay. Tom is a persuasive, influential writer, but his article misses the mark in important ways.

Sarah O’Keefe and Alan Pringle contributed to this post.

Let’s start from the conclusion:

I don’t want to come across as being against structured authoring. As I mentioned in the introduction, clearly structured authoring is a trend many companies are following. However, structured authoring has a few challenges before it can live in a web environment. In this post, I mentioned a few trends that I think pose challenges to structured authoring:

  • SaaS decreases the requirement to support versioned content.
  • Agile makes print publications potentially out of date every two weeks.
  • Collaboration requires a form that SMEs can edit, update, and potentially author themselves.
  • Mobile works best on a website with responsive design.
  • Budget cutbacks force small teams to figure out their own publishing solutions.
  • Open source platforms provide a lot of capabilities that we can easily leverage.
  • Browser-based editing simplifies the update process, which helps us keep up with rapidly changing information.

Here are some counterpoints:

SaaS. What percentage of companies are producing just SaaS products? The dubious assertion that SaaS eliminates the requirement to version documents dismisses medical devices, pharmaceuticals, and all hardware products from consideration. Many companies that offer SaaS options also have packaged software.

Agile. Agile is definitely a challenge for print publications. But what does print have to do with structured authoring? The true question is, “Should we create print or not?” The underlying methodology is irrelevant—unless you are conceding that web-based authoring doesn’t really support print. And again, what of industries that require print or PDF?

Collaboration and SME editing. It’s possible to give subject matter experts direct editing access to either XML or HTML. Don’t want SMEs to have final say in the modifications they make to content? Set up their access to enable changes that require approval; there are hosted systems for managing structured content that provide tiered account access.

Responsive design. This one had us truly puzzled. Generating content that uses responsive design is a configuration issue, so it’s easily done in whatever technology you have that produces HTML and CSS. But then Tom asserts that using responsive design from XML means that you are ignoring multichannel publishing. This is true only if your multiple channels are “desktop” and “mobile.” But most companies are also producing PDF/print, and we are seeing increasing requirements for EPUB (yes, EPUB!!!), XML for consumption by other systems, and more.

Budget cutbacks. From the body of the post:

With many tech writing teams constrained with small budgets and few resources, hiring a dedicated publishing engineer to handle the transforms, or contracting out the work at a high cost, really isn’t a practical solution.

Look at all those scary adjectives! In response, we’ll ask our standard consultant questions: Is there a business case? Nobody hires “publishing engineers” (which, by the way, is a great description of the job) or contracts work out at “high cost” (another happy phrase when we’re on the receiving end!) unless there is value in doing so. What is the value?

Open source platforms. You’ll get no argument from us that open source platforms “provide a lot of capabilities”: WordPress has its place, as does the DITA Open Toolkit and all the open source technologies it includes. What’s important to remember about open source tools is that they usually require tailoring and the addition of new features to fully meet a company’s particular needs. Yep, it’s time to haul out the “free but not cheap” chestnut: the default implementation of any open source technology is rarely enough to meet your requirements, so be prepared to spend time and money to implement all the features you need. Some companies may calculate it’s cheaper to buy a tool that fulfills their requirements out of the box instead of trying to build a comparable open source solution.

Browser-based editing. Tom says that “you shouldn’t have to author outside the browser to publish on the web.” Well, you don’t have to. Multiple hosted systems for managing structured content include browser-based authoring and editing. That said, there are good reasons why a company may not want browser-based editing or any hosted tools: bandwidth limitations, security, and so on.

What’s missing from Tom’s discussion is a recognition that business requirements should drive the decision on structured authoring, the formats in which a company provides content, the selection of open source or proprietary tools, and so on. Instead, his post creates a narrow rhetorical funnel (if you make SaaS software and eliminate PDF and have no resources) and then asserts that a particular solution is best. Given the constraints Tom describes, you can make a case for web-only authoring. But what percentage of tech comm actually falls into this very narrow description?

Finally, we didn’t see any recognition of key tech comm requirements—localization and conditional content—that often drive tool decisions.

Structured authoring and the web aren’t mutually exclusive. You can combine both into a useful, dynamic approach to content.