Review: Publish Help Content on WordPress with easyDITA

Let’s look at a pair of emerging trends:

It’s easy to see why authors / publishers of technical documentation would want to connect those dots: make authoring less time consuming, and streamline publishing of all content, for starters. And getting docs out from behind firewalls to where they’re findable by normal searching is becoming SOP for companies that understand the power of technical content before and after the sale. Which brings us to easyDITA’s new WordPress publishing engine and its Knowledge Portal theme. In a nutshell, this new combination from easyDITA addresses the challenges of delivering documentation via the web that impact both large enterprises and smaller businesses.

EasyDITA lets you create structured content with the Darwin Information Typing Architecture (DITA) in a web browser, and publish it to a variety of formats using the DITA Open Toolkit. If you work in a large organization with extensive and complex tech docs needs, you probably already know the business case for implementing DITA. Now you have more options that let you take advantage of existing WordPress installations, and leverage branding within your online technical content. If your resources have basic DITA skills and non-coder knowledge of WordPress, you can have a branded knowledge portal up and running in short order.

The new WordPress publishing option is a little less “easy,” at least at the beginning, but should be a good fit for even small software documentation shops familiar with integrating with APIs like WordPress. If you have not already forged a collaborative routine with your company’s web developer(s), moving structured technical content to WordPress represents a very good time to start.

I spent some time playing with this integration and offer a few ideas on installing and configuring easyDITA for WordPress that can make your implementation a little smoother.

Preparing your WordPress Site

Let me get the stuff you might think of as scary out of the way first. After signing up for WordPress Publishing with easyDITA, you’ll need to some WordPress “development”, after a fashion, to make the integration happen.

No need to run away though, because you won’t have to write a single line of code. Just fill out a form to tell WordPress on which site you intend to put this integration tool (easyDITA’s brief documentation tells you how to fill it out).

If you haven’t made contact with your web developer(s), this is a good starting place, because they are likely well-equipped to handle this task.

WordPress.com vs self-hosted WordPress

One especially nice factor to consider is that easyDITA can publish to any WordPress site for which you have credentials, whether it is hosted on the (free) WordPress.com platform, or a WordPress installation hosted somewhere else. If you have an existing WordPress site you can add your documentation portal as a subdomain of that site. If you host your WordPress site with your own hosting service, you will need a WordPress.com login to continue the process. This is free and only takes a few clicks to set up.

If you are not running your site on WordPress.com, you need to activate the Jetpack plugin from Automattic (WordPress.com), which requires a connection between your site and WordPress.com. Install Jetpack (installation is as easy as installing any other plugin), and then connect with WordPress.com.  Jetpack’s Javascript-based (JSON) application programming interface allows easyDITA to log in as a user and post securely using the OAuth authentication standard.  (Note: Installing Jetpack is a smart step no matter what; you will find many other good reasons to have Jetpack running on your content management system.)

JetPack

Figure 1: Activate the “JSON API” to allow easyDITA to publish to your WordPress site.

Extra Tweaks

I found that publishing with easyDITA works best on a new site with minimal customization or a new subdomain of your existing site.  This is because if your theme uses custom menus to organize your navigation, you need to de-activate them. When you publish, your help will add itself to the default navigation configuration for your theme. Or, you can use the easyDITA Knowledge Portal theme (you can add it to a subdomain and publish without affecting the parent site), which we’ll get to shortly.

Publishing Your Content

Now you’re ready to publish your content to WordPress — a nice and easy experience, especially if you’ve used easyDITA before. You create your content and maps in easyDITA’s online editor, add links and graphics and whatever else to make your help sing. It’s time to publish.

Figure 2: Editing DITA text in easyDITA

Figure 2: Editing DITA text in easyDITA

You can choose between the standard DITA Open Toolkit and WordPress. When you click WordPress, your account/site will be listed. (Consultants take note: You can set up multiple accounts to produce help for different client sites. Use the drop-down menu to select the right location.)

Figure 3: WordPress Publishing

Figure 3: WordPress Publishing

Type your title in the field (this will be your menu title on the site), and click Publish! And easyDITA goes to work. When complete, the Publish page gives you a link to your site, and there you are!

Your content appears as WordPress Pages, and the menus follow your map. You will want to test your site before going live. Some themes do better at picking up the DITA-specific classes that easyDITA identifies in the HTML output. For example, I created some glossary entries that easyDITA outputs to “topic-dt” and “topic-dd” (term and definition) that some themes didn’t display properly (Figure 4).

Figure 4: Some themes don't work well with easyDITA's custom CSS tags.

Figure 4: Some themes don’t work well with easyDITA’s custom CSS tags.

One way around this problem is to tap the web developer’s shoulder (again), and ask them to create a child theme to customize the display of your special tags with your existing theme. Another way is to simply take advantage of the easyDITA Knowledge Portal theme.

Using the easyDITA Knowledge Portal

Content developers in both large and small teams have been longing for a way to bring tech docs into the WordPress world. Happily, easyDITA provides a free theme, the easyDITA Knowledge Portal, which is already available at GitHub,  will soon be available at easyDITA.com, and eventually in the WordPress.org Theme Directory.

The Knowledge Portal installs like any other WordPress theme, and is customizable before or after you activate it for your site. In addition, the folks at easyDITA created a responsive theme, which optimizes your content for a variety of screen sizes without any extra work on your part,

One of the cooler features of the Knowledge Portal is the ability to distinguish help content from the rest of the site through the use of Custom Content types. Identify each page generated by easyDITA as Content, FAQ or Tutorial in the WordPress page editor.

Conclusion

EasyDITA offers WordPress users an excellent way to publish technical content on their sites, and reach prospective customers as well as current users. WordPress.com site owners gain the added benefit of minimal setup requirements.

Some gotchas should be considered before adopting easyDITA for WordPress:

  • Compatibility with your existing theme
  • Whether you use custom menus on your site

You can resolve those easily if you go with the easyDITA Knowledge Portal theme, and make your documentation site a subdomain of your existing site.  You can see a great example on easyDITA’s own site documentation.easydita.com. The folks at easyDITA even offer a nice tutorial that shows how they did it. If you plan to go another route, spend some time with your WordPress web developer, who can help you solve a range of problems you could encounter.

Figure 5: easyDITA's documentation site published with the Knowledge Portal theme

Figure 5: easyDITA’s documentation site published with the Knowledge Portal theme

Independent consultants who work with small businesses typically have clients that think structured authoring with DITA may be overkill. The easyDITA WordPress publishing solution works well for these folks, as well as larger companies that have already started down the structured content road. If you have multiple clients keep in mind that you could incur some overhead in creating multiple apps for each client. No matter if you fit this consulting niche, or manage a team in a large organization, easyDITA for WordPress and the Knowledge Portal theme, present a powerful, cost-effective, and quickly deployable solution for getting technical content to the customers and prospects who are looking for it.

 

 

Mike McCallister

Mike McCallister is devoted to the idea that technology need not be feared, and can be mastered by anyone. After all, he grew up in the days when computers filled entire rooms, and spent 13 years as a civil service clerk doing nothing more technical than recording WordPerfect macros. Mike is also devoted to making computing easier for the full spectrum of user levels and experience. You can connect with Mike through his Google+ page.

Read more articles from Mike McCallister