Update on the Search for Enterprise Authoring

So many different paths.

So many different ways to go.

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 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.


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.


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.


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

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Ramakrishnan

    Wow! Great summary!!

    Re: tri-pane help output. While publishing HTML Help (CHM) using WinANT, we found that the project file that was generated along with the CHM output could be opened in RoboHelp from where the tri-pane WebHelp could be published.


  • http://idratherbewriting.com Tom Johnson

    Thanks for the tip, Ram. It’s interesting that it could be opened directly in Robohelp.

    • Ketan Sevekari

      A Wiki is an ideal collaboration platform. It takes less effort to setup and implement than a DITA based system. Also you might need proprietary software software if you plan to use DITA. A HAT tool like Author-IT is again proprietary. So why go for proprietary and costly software if you have good free alternatives available.

      I haven’t used WordPress, but I can vouch for a wiki’s collaboration features.

  • VS

    Have you considered SDL Trisoft? http://www.sdl.com/en/xml/products/sdl-trisoft-dita/default.asp

    I’ve used it at a previous employer. It’s a DITA-based tool. It lets you do all the things that you have mentioned as requirements, except for the Wiki functionality. (Maybe they have a Wiki functionality, but it wasn’t used by my team.)

    There will be other tools similar to SDL Trisoft that may give you more features for lesser cost. Let us know what solution you went with.

  • http://www.whytechcomm.com Kristi

    I wonder if you could build momentum by picking one project with one other department and creating a solution for that product with the assumption that you will use tools that your departments already have.

    So many tools now provide ways to publish to various platforms and to single-source, or at least import and export content in various formats.

    If he or she were working from a familiar tool, is there someone on your team who would be willing to take on learning some development skills to bridge the technical gaps you will run into trying to do this?

    Once you had success without spending an outrageous amount of time or money, maybe you could team up with a third department, or get more buy in for gathering and enforcing requirements.

    Maybe it’s not reasonable to expect many people to switch tools. Maybe most of them can publish with familiar tools if the content, eventually, ends up being single-sourced from a single repository. After you have buy-in.

    By the way, there are some good threads going on the Flare forums for how to customize WebHelp output and make it more searchable.

    • http://idratherbewriting.com Tom Johnson

      Kristi, thanks for your comment on this. You have so many good insights. We had a long meeting last Friday and decided to mostly stick with our current approach, which is to use Flare. In comparing HATs, Flare has so many compelling arguments — a new one with Flare 7 is the SharePoint collaboration platform. Our dept has a strong SharePoint infrastructure, and hosting our files on SharePoint can be an easy win for findability across the enterprise.

      As far as gaining buy-in across the enterprise, we realized even among our own team how stubborn we are with our toolset. When something is working well, it’s hard to find a reason to use another system, even for a tech-savvy group like us who is open to new tools. We are also too small to enforce a new tool at an enterprise level.

      Can you point me to the Flare forum posts discussing search? This is a major point of interest to me.

  • http://camaro-parts.info/1991/ Camaro hoods

    I like the blog, but could not discover how to subscribe to obtain the updates by email.

  • http://camaro-parts.info/1991/ 1991 Camaro parts

    Hi, I am not able to see your site correctly inside of Chrome browser, I am hoping you can look into fixing this.

  • http://www.ifcatscouldwrite.com Gina Wadley

    I am so glad I found your posts on this subject because our team is going through the same issues. I agree with you on your comments about DITA. It is so much work converting our existing docs in RoboHelp and Flare into DITA. Also, I don’t see how we can take advantage of reusing content without an authoring assistant that automatically suggests text as you type, like SDL’s AuthoringAssistant, which I reviewed on my blog at http://www.ifcatscouldwrite.com/2011/06/16/review-of-sdl-authorassistant-2010-for-framemaker-9-and-10/.

    We’re currently reviewing some integrated applications to solve for:
    DITA XML editor
    Converting existing FrameMaker,Flare, and RoboHelp to DITA
    Component content management system
    Authoring assistant (suggest as you type based on translation memory)
    Localization integration features
    WebHelp and PDF output

    While my personal preference is to focus on customer collaboration and feedback, we also need to solve for reuse and localization costs. I think we could still capture our customer’s suggestions and feedback and convert that information to topics with DITA.

    We also use SharePoint, but haven’t tested it as a component content management system. I’ve seen that you can do some advanced searching for your content, but we want something like the authoring assistant with automatic suggestions. I don’t see how it would work without connecting to your translation memory.

    How are you planning on reusing your content between the tech writers?



    • http://idratherbewriting.com Tom Johnson

      Gina, thanks for your comment. At the moment, we’re going with Author-it for our enterprise help authoring solution. It has most of the features we need, especially with localization. There’s an extension that checks to see if what you’re typing has already been created somewhere else (I can’t remember the extension’s name, sorry.)

      I’m not the one implementing the solution, though, so I haven’t had much to say about it. Also, we’re still piloting Author-it to test its viability.

  • http://www.ifcatscouldwrite.com Gina Wadley

    I was about to download the Author-it trial because it looked like a turnkey solution for us. But then I read somewhere that you can’t create DITA content with it (I think you can only import the content and output it). I don’t know much about it so maybe someone else can tell us. We like FrameMaker because you can use it to create and edit DITA.


    • http://idratherbewriting.com Tom Johnson

      Creating DITA isn’t our highest priority. I think Author-it does export to DITA, though. But I’m not sure.