Update on the Search for Enterprise Authoring

by Tom Johnson on Mar 8, 2011
categories: technical-writing • wordpress

It's been a couple of weeks since I posted about my team's search for an enterprise authoring strategy. So far, we're just as split as ever about the problem. It seems that you can go four separate routes: DITA, HAT, Web, or Wiki. Here are some of the paths and difficulties we're encountering.

DITA

DITA has traction as a new standard format for help authoring, but the DITA Open Toolkit output isn't attractive out of the box. Further, the HTML output is a far cry from the tripane help output, which we're accustomed to seeing from traditional help authoring tools.

While DITA is a cool idea, relinquishing control over the way the help looks will hurt our chances of getting buy-in from other groups and will leave us powerless to meet the needs of project managers who ask for some customization beyond margin adjustments and typography.

Scriptorium has a DITA PDF and tripane help plugin, which looks promising (see A makeover for the DITA OT's PDF plugin). I caught a glimpse of it in the Attractive DITA webinar. Scriptorium is up front about pricing -- $10k for the PDF plugin, $4K for the tripane help plugin.

Although I like the idea of the DITA standard, I dislike the idea that I would need to be a programmer to control the output. That puts our team in a position of vulnerability that none of us wants to accept. About the only solution in the short term is to hire a consultant to make the help look decent, and then just leave it be. Leaving the output fixed does score a point for consistency, but my team is design savvy and used to being in control.

HAT

Another path might be the help authoring tool (HAT) route, using tools such as Flare, RoboHelp, or Author-it. Flare has just released version 7, which allows collaboration through SharePoint as a file repository. This would be great, since we have a heavy SharePoint environment at my work. Author-it, another strong HAT, has a mind-blowing plugin called Author-it Live that allows a logged-in user to edit the online help inline similar to a wiki.

HATs are compelling because they seem to offer a complete solution with granular control over the output. The only problem is that each author usually needs an instance of the HAT, which is about $1,000 each depending on the tool. The Author-it Live solution allows concurrent licenses to the product, so the users don't need to be dedicated -- just limited to a certain amount of users at a time.

Author-it is attractive because another group in our organization already purchased this solution (but hasn't implemented it yet). Also, the tool is robust, which is something we welcome. But trying to force the tool on others in surrounding departments who may not be technical or open to change will be an uphill battle. It's hard to go to other groups and say, Here, buy our tool, learn our ways, use our output profiles when they already have a simpler solution that seems to work for them.

Web

Neither DITA nor HATs provide a Web 2.0 output. We're all conscious of the fact that tripane help is a relic of 1995, and invites as much confidence in users as a station wagon. While Sarah O'Keefe suggests that actual user standards for document design are probably below our own -- that is, users are more interested in the content, not so much in how it all looks -- we want our help to fit in line with the current century.

Many web content management systems, such as Drupal or WordPress, provide an abundance of web elements that speak the same language as contemporary Internet users. Categories, tags, comments, RSS feeds, most popular posts, multimedia, jQuery -- it's all available in one experience in a website format.

The problem with these web CMS formats, though, is that you sacrifice content re-use and printed output. At most, a topic on a web page may be printable by itself. Web developers don't care about re-use, so this is not a feature you'll find.

We were excited to see that EasyDITA exports to WordPress, even though such an export from DITA is already available through a free plugin. Unfortunately many organizations, including our own, don't support MySQL / PHP solutions. And even if they did, we're skeptical that a WordPress theme could offer a navigation-friendly table of contents for hundreds of topics. And once you output to WordPress, there's no round-tripping back into EasyDITA.

Some developers in our organization actually built a WordPress-like CMS, which they use to run the Newsroom. Amazingly, it uses our Mark Logic XML database on the backend, so theoretically we could write some XQuery scripts to get the content re-use and printed output that we need. But none of us knows how to do this, and we're not so excited to adopt an XML solution that doesn't involve DITA.

Wiki

Wikis such as Confluence and Mediawiki have appeal because we do have a large volunteer community. We're already using Mediawiki for these volunteers, and it seems to be working in some areas. For example, the LDSTech wiki has regular contributors, and FamilySearch apparently has 50,000 Mediawiki pages with genealogy content.

I love the ease of collaboration that wikis offer, but they do a poor job with traditional help authoring requirements, such as selective re-use, access control, multi-channel publishing, and so on. Wikis can be styled with a Web 2.0 look, but most wikis I see are sprawling atrocities with column widths spanning the entire length of the browser, and no attempt at a table of contents.

Also, it seems that I am the only person on my team even remotely interested in wikis. On top of all this, I struggle to make community efforts worthwhile. (See my post, Do Community Efforts Work?)

Wikis do have a strong pull, though, since our organization wants to move more toward community integration in the future, with goals as ambitious as having 80 percent of the work done by volunteers.

Future Requirements

The most troubling problem in our enterprise strategy is that we're pursuing a solution based on hypothetical requirements. There isn't currently an enterprise-wide authoring practice, so finding a tool that is easy to use, collaborative, standards-based, cost-effective, and has attractive PDF and web output is based on the idea that people in various departments will actually adopt our solution and fall into line with the new methodology.

Our next big question is this: Once we select/compromise on a tool, how do we take it enterprise-wide? We don't want to push the issue too early, or we'll get every tribe vying for his or her own preference. If we get our own house in order and push our solution after figuring out what it is, we risk formalizing a solution that doesn't meet their needs or wants of all the surrounding departments. We may end up with an approach that is designed for the enterprise but in reality is only used by us.

-------------

photo by Christine Selek on Flickr