If you've been following my posts lately, you've seen me explore the tools question numerous times. In this post, I'll explore combining structured authoring with web publishing on WordPress.
In a nutshell, here's the main idea: structured authoring tools are great for authoring content. Web platforms are great for publishing content. My plan is to leverage the best of both worlds by creating content using an XML editor like OxygenXML, and then publish it to a platform like WordPress.
Unquestionably, authoring content with a tool like OxygenXML or another editor is preferable to authoring in a web CMS. Every web-based CMS that I've ever used — WordPress, Joomla, Drupal, Google Docs, and even Mediawiki — have all been less than desirable for creating and editing content. These platforms make it easy to publish content, but when you're writing book length material (that is, 100+ pages of a technical guide), you have greater authoring needs.
If you try authoring all your content in an online CMS like WordPress, you'll soon be pulling your hair out. Here are a few frustrations that happen if you try to authoring your content in WordPress:
Overall, if you attempt a large scale, complex authoring effort in a platform like WordPress, which is really designed for writing standalone blog posts, you're setting yourself up for frustration.
I'm not saying it's not possible, and if you have simple requirements, you could probably work around all of these limitations. But in my previous job, I worked for about 15 months using nothing but Google Docs and Drupal, and I found the authoring experience to be somewhat challenging. I missed working with my help authoring tools. I longed for a tool that understood my needs as a technical writer.
Before I trash online CMS platforms too much, let me flip to the other side of the problem: structured authoring tools produce poor outputs, for the most part.
Although they're great for authoring content, neither help authoring tools nor structured editing tools seem to publish content in an impressive way on the web. One might say it's unfair to criticize an XML editor for its output, since the whole idea of XML is to separate content and publishing. But at some point, you have to apply a transform to publish XML content, and unless you're developing your own custom transforms, you'll use what's available.
Most of the webhelp outputs available for structured content are frame-based. They look like they belong to the pre-2000 web. Tripane help outputs are hard to customize, they don't display well on mobile, and they lack a lot of the interactive, social functionality of the modern web.
The TOC-heavy paradigm of structured content outputs is the most problematic aspect. Almost all webhelp outputs load up the left or right sidebar with an innumerable number of topics (a massive table of contents) and require the user to expand folders and subfolders and sub-sub-folders to find content. It's essentially the book paradigm transposed onto a web interface.
And yet, almost no complex website publishes its content through a massive table of contents in the sidebar. In fact, tech comm is probably a decade behind web usability in terms of online findability and navigation. Yet this TOC-based navigation is the default paradigm of structures like DITA. The default setup is to create a map file that is a long TOC with various levels of hierarchy.
There are a few DITA vendors in this space with decent looking web outputs, such as Fluid Topics, SuiteShare, DITAweb, WebWorks, and more. But none of them is cheap, and none of them breaks out of the TOC paradigm.
Additionally, there are a few open source HTML help solutions that you can leverage with DITA that look modern (for example, see this Salesforce branded site (which was kind enough to open source its code).
However, I'm not just talking about display. Almost none of these platforms, regardless of the modern look of the display, has the functionality of WordPress for publishing.
A help center doesn't consist solely of a display of articles. Here are a few other features you can easily add to WordPress to integrate more assistance-oriented features:
I don't mean to dive into each of these features in this post. Instead, I'm simply introducing a new series here that will explore publishing DITA tech comm content with WordPress.
Overall, while you can probably do many of these things with a regular HTML site, you probably can't do them in 10 minutes. With WordPress, you simply leverage a lot of plugins, themes, and other code samples already developed.
For a brief moment, let's dive into one of the most important features: commenting. Interactivity with comments is probably the heart of the benefit of a WordPress site. While you can get a lot of mileage out of using a tool like Disqus integrated into a webhelp output, WordPress's commenting features are fully developed:
Many different platforms offer the ability for users to comment on pages, but sometimes the commenting features are pretty simple.
For example, I explored using Oxygen's Webhelp with Feedback output as a means of allowing reviewers to comment on pages. Before I could fully test it, the commenting system broke and I couldn't figure out how to fix it. Overall it felt like a simple feature that was quickly tacked on in a few weeks of coding effort, whereas WordPress' commenting feature is one of its core strengths and is probably more robust than most other tools.
Probably the greatest strength of leveraging a platform like WordPress is the ability to build on already-available components in order to create a solution. Developers all over the web have already coded beautiful, functional components that you can either purchase cheaply or install for free to get the functionality you want. There's no need to spend time rebuilding or redeveloping all of these components from scratch.
For example, take a look at the Ubermenu. For about $20, you can buy a pretty cool menu that is responsive out-of-the-box, takes a few clicks to install, and allows you to break out of the TOC paradigm in interesting ways. Sure you could have internal front-end designers build a similar feature, but how long would it take, and at what cost?
As a general strategy, we get innovation by piggybacking on each others' efforts. We build on server technology already available to deliver our content. We leverage themes already designed that maximize usability and responsiveness. We use login systems that have already been created to authenticate users against existing protocols. We don't build all of these technologies from scratch every time we need them.
Imagine if every time you wanted toast, you had to build a toaster. Or if every time you wanted electricity, you had to rig up your own dam and coils and run power lines.
This is how innovation works. We don't start over every time. We leverage existing technology and innovate on top of it. With WordPress, most of this functionality is already developed and ready to incorporate into your project.
When you consider the pace of innovation on the web, no tech comm vendor will ever be able to keep up. Can you imagine a vendor offering all the functionality in their platform I listed above?
In contrast, there's a WordPress plugin for virtually any need or situation because its community is so vast (WordPress powers about a quarter of the websites on the web.) No vendor can sanely can offer all of the features that a popular platform like WordPress does. And the pace of technology is only increasing. How can traditional tech comm publishing solutions ever stay current?
In the coming weeks, I'll be exploring the publishing workflow with WordPress in greater detail. At work I have a WordPress multisite set up internally for review of my help content. So far it's working well. There are a few limitations. And I suspect I'll have to eventually consider whether authoring in an external tool is really worth it. But for the time being, this is my workflow: author in DITA, publish with WordPress.
For instructions on importing DITA into WordPress, see the topic in my DITA QRG called Import DITA's XHTML Output into WordPress.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.