Author in DITA, publish with WordPress

by Tom Johnson on Aug 19, 2014
categories: dita • wordpress

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.

Tech comm is great at authoring

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:

• If you have to create, delete, rename, and move around many pages frequently, it's going to be really tedious doing this in a web-based CMS. For example, if you want to delete a page, you can't just drag the file into the trash. You have to go to your list of pages, find the page, click the delete button below it, and eventually empty it out of the trash so that the permalink the page was using is freed up. And with each navigation point, the site has to load for 1-2 seconds. When you make hundreds of these little edits every day, it makes authoring really cumbersome.
• If you add a code sample with angle brackets in Text mode, and then switch to Visual mode and back to Text mode, the rich text editor will remove the code.
• If you try to add list formatting with the Visual editor, you end up wrestling it when you try to account for lists broken up by notes, screenshots, subsets, results, and so on. If you switch to straight HTML authoring, it's hard to keep all the tags straight (remembering whether to close or not close a list item based on whether there's a paragraph or image following it, and such). Plus, writing everything directly in HTML is simply cumbersome (this is why Markdown is such a popular syntax for HTML writers).
• You can't see prompts about what tags are allowed at different points in your document, nor can you see prompts about the allowed attributes and values for each element. You also can't troubleshoot invalid content by looking at prompts listing reasons for errors.
• You can't link topics with each other in ways that update automatically even if the other file name changes.
• If you need to do a find and replace across all files, you have to do a database query. (Also, you better hope you get the syntax right or you'll see all kinds of funky character codes in your content.)
• If you ever need to publish a full PDF, good luck. Almost no WordPress tools are designed to create a PDF from anything more than a single page.
• You have to be online the whole time to write and edit content. If your browser freezes, your wifi goes offline, your computer goes into sleep mode and shuts off your wifi, or if you're on a plane or somewhere where there isn't wifi, your productivity drops.
• You can't easily re-use content for different audiences. If you have a publishing solution requiring any degree of complexity, such as creating six different outputs (2 products across 3 programming languages each), you will struggle using WordPress. Imagine having to update the same paragraph on six different WordPress sites. You just can't keep so many sources in sync manually. Instead of re-using content for different audiences, with web formats you see a lot of tabbed interfaces that show different programming language snippets or which explain different version notes integrated into the same page for all products.
• You can't enforce a specific structure. This means that across writing groups, the content will be less consistent and predictable.

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.

Web platforms are great at publishing

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:

• Role-based views
• Forum
• Chat
• Related posts generated by algorithm
• Search engine optimization
• Custom google search
• User tracking and analysis
• Security
• SAML and LDAP integration
• The ability to import XML
• jQuery menus
• User profiles
• Social networks (like Ning)
• Ability to import RSS feeds
• Ability for users to subscribe to RSS feeds
• Tabber widgets
• Shortcodes
• Embedded maps
• Embedded videos
• Responsive design
• Multisite management
• Syntax highlighting
• Site backups
• CDN networks
• Pingbacks
• Categories, tags
• Integrated blog
• Expand and collapse
• Distributed authoring
• Authoring workflows (from draft to publication)
• Revision history
• Social sharing buttons
• Custom post types
• 32,000 plugins that do pretty much everything

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.

Robust commenting features

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:

• Users can reply to replies (nesting threads several levels deep). This is sometimes referred to as threaded conversations.
• The author's comments can appear with a special styling. This helps readers know at a glance which comments are the official responses to questions and criticisms.
• Users can subscribe to comment threads (by RSS or email) and be notified of updates.
• You can auto-close comment capability on old pages, or close comments on a page-by-page basis.
• You can integrate plugins like Akismet to handle spam.
• You can aggregate comments across all pages into a central display, such as on your homepage or a sidebar.
• You can choose to moderate comments before publishing them.
• You can integrate social login plugins so users can sign in through Twitter, Facebook, or Google.
• You can control how many comments appear below a page before the user must click to see additional comments (so that your page doesn't become infinitely long with 100+ comments).
• You can reply to the comments in a central interface on the backend so that you don't have to visit each page directly to add your replies.
• You can define who should be sent an email when someone comments. The email could go to an alias that gets distributed to a support team.
• You can integrate comments into a live comment feed that dynamically cycles through the comments and makes your site look more alive.
• You can integrate plugins that allow commenters to annotate in the margins rather than at the end.
• You can customize the commenting form itself.

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.

Cost and custom development

• WordPress is free. You won't need to put together major budgetary proposals or get alignment with dozens of stakeholders before you can move forward with a solution. This is something you can probably hack together in a weekend as a proof of concept.
• Even when there's a cost associated with a plugin or theme, the cost is minimal (usually under $100). The time the plugin or theme saves you is well worth it.
• If you want to pay someone to build a custom plugin, you can do so rather cheaply, for probably under $2,000. There are many WordPress developers you can find to build the functionality you need. In contrast, when you work with a specific tech comm vendor, you're reliant entirely on that vendor (or the vendor's partners) for functionality enhancements.

Modern, branded interface

• You can buy a slick, modern looking theme for around $50 and install it with a few clicks. This saves you the hassle of designing one yourself. You could also hire someone to custom brand a theme that matches your corporate site for as little as $1,500.
• You can easily make adjustments to the theme with some basic knowledge of CSS and a bit of familiarity with WordPress theme files and tags. You can customize the heck out of anything. And there are thousands of tutorials online to show you how to do just about anything.
• Many of the themes look modern and stylish. You won't be embarrassed by the output. Since many managers don't read help anyway, you'll score an immediate win with this crowd.

Strategic advantages for innovation

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.

Keeping up with the pace of innovation

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?

Upcoming posts

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.

Related links

For instructions on importing DITA into WordPress, see the topic in my DITA QRG called Import DITA's XHTML Output into WordPress.

Next: 1.2 Challenges in using WordPress for publishing DITA content