The Enterprise Help Authoring Problem

In my organization, we’re in the middle of trying to come up with a solution to address enterprise-wide help authoring. Currently we have a lot of pocket groups of writers working in silos. We think an enterprise-wide solution that unifies help authoring would be a step forward.

Siloed Publishing versus a Unified Help Strategy

Siloed help authoring (left) versus a unified help authoring strategy (right). How do you make this shift?

I would love if it someone could recommend a solution. Here are our requirements.

Enable consistent-looking, attractive deliverables. Currently help across the enterprise takes all shapes and formats, since most authors work in silos using the tools they choose. Help produced by the different groups looks as different as help produced by separate companies. We want to create a consistent –and attractive — look and feel to help materials produced by our organization.

Enable non-technical people to author. Sometimes non-technical writers, such as domain experts in business departments or project managers, need to author content. We need to a process that allows them to author comfortably without getting hung up with complicated authoring methods or tools. A simple authoring solution would also increase the likelihood that writers from the various silos embrace our solution.

Allow community members to collaborate. We have a wide number of community members who also need to collaborate on content as well. Community members are outside the firewall and may have only rudimentary technical skills. These community members volunteer their time and talent to work on documentation and other content projects. We need them to be able to author content, too.

Share and re-use content. We need to share and re-use the content that we create. We may be mixing and matching different topics in different outputs, and also working collaboratively on the same project. We want to leverage content re-use where necessary to allow us to compile different deliverables that draw upon the same content base, such as online help and printed guides and training guides.

Translate content. Much of the content we create needs to be translated. Translation department requires the content be in Word, XML, or UTF-8. Another translation group uses LingoTek.

Allow users to easily find the content. In addition to improving the authoring process, users also need to easily find the content. Some departments have thousands of pages of content. We need a way for users to search through that content to find the right information quickly.

Permission levels for certain kinds of content. Some content is permission-based, so only users in certain roles should be able to access it. All users with these permission level requirements have their role identified through a central identity access management system.

We’re open to any solution at this point, and cost is not an overriding factor in the solution. We do have a thorough SharePoint integration internally as well as a robust Mark Logic database. Externally some content is on Mediawiki. Because of the size of the organization, we do have a lot of in-house experts. What would you implement for this situation?

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.

  • Mary Connor

    I’m currently implementing a silo-busting solution that meets many of your requirements: getting the global production team authoring in familiar tools, single-sourcing automated publications, repurposing content, and supporting localization. It uses Doc-To-Help, and the source is managed alongside our code in Team Foundation Server. I’ll be explaining the strategy in a series of blog posts coming up, which I hope will help.

    • Tom Johnson

      Thanks Mary. I’m interested to hear your Doc-to-Help solution. Does it require authors to use Doc-to-Help, or does it involve some kind of Word template import? Are you integrating Doc-to-Help with SharePoint somehow? I checked your site for posts on the topic, but I think you’re still in the process of writing them. Thanks for your comment.

      • Mary Connor

        No, my solution is about plain Word files under any kind of version control (we could use SharePoint but aren’t), then having Doc-To-Help running on a build machine, with batch files that copy down the latest Word and HTML files locally for the nightly build and publishing. SharePoint will be coming in for the localization aspect, for managing the translation process and automating D2H builds of those other language targets. I’ll get moving on posting this all to my blog!

  • Marcia Johnston

    Great questions. I’d like to hear about companies who have editors on staff still… or again. I know of one company that’s trying to reinstate — actually instate (they’ve never had an editor before) — this role to address at least some of the issues you raise, Tom.

    • Tom Johnson

      Marcia, I think editors are becoming more important than ever, but not in the traditional way. Technical writers are changing into editors to facilitate SME-written material. In other words, we are serving editorial roles for content that business experts are editing. The traditional editor for technical writers themselves is a dying role, though. Just look at the job postings — dedicated editors are on the endangered species list.

  • Melissa G. Steiner

    I’m a big fan of Author-it and I think it solves almost all of the issues you raise. While we have not fully implemented Author-it for our enterprise, we have been able to blend two authoring groups into the use of one tool and we maintain permission-based access to content.

    We are implementing a reuse strategy such that we can write the content once and re-purpose the same text to different audiences; we write the basic content for our external customers and then wrap internal-specific content around that reused, basic content for our internal audiences. By approaching our reuse strategy this way, our internal audiences see exactly the same text as our external customers but they have the additional troubleshooting steps as a wrapper.

    Because of the robust importing functions of Author-it, we are able to use content that is written by other contributors in the very commonly used Microsoft Word as well as importing help content authored in RoboHelp or any tool that can export to HTML or XML. This also means that we are able to share translated materials and also send our English content off for translation using XML as the shared file format.

    To date, we are using Author-it to delivery compiled help (our desktop help solution) and webhelp (our online help solution) using the exact same content (and we are doing the web versions in 6 languages). We will be implementing a paper-based delivery in the near future.

    • Ben Mansheim


      I agree with Melissa that Author-It can handle all of the authoring requirements that you have. We have been using Author-It for over two years with multiple locations, a wide range of projects and translation.

      I am an Author-It believer.


    • Tom Johnson

      I know Author-it is a favorite tool of many, but I’m wary of the Word-import process. Other HATs provide this as well (Flare and Robohelp). But importing content from Word is usually problematic. Also, it requires a person to have the HAT to run the import and manage content within the tool. In my situation, we have probably 10 different authoring groups across the enterprise. Having them all switch to Author-it and run Word imports doesn’t seem practical to me. It feels very old-school. I want them to author directly in the format that the content needs to reflect.

      • Noz Urbina

        Hi Tom, what did you mean by that last sentence? Author in the format that the content is to reflect??

        • Tom Johnson

          I think I’m resisting against the Word template imports. I’d rather have users author directly in a Word template that contains the DITA structure, and then by placing the Word file in a folder, voila, it gets transformed into the output.

          I don’t want to import files into a HAT to have one person convert them into the HAT’s proprietary format. I have a colleague who tried that with another project and he ran into major problems. His templates caused all kinds of issues, including style conflicts, crashed computers, frustrated users, etc.

          I recognize that Word seems to be the defacto authoring tool in the enterprise, but I want to get away from the HAT import with those templates. I’d rather have the transforms directly work with the content.

          However, I also recognize that some HATs work as a much simpler process for creating the transforms that one needs for the stylish outputs. Since I don’t know XSL or xQuery, I might be better off using a HAT to do the transforms. Oh well.

          • Noz Urbina

            Hi Tom,

            Agreed – anytime you flatten back to unstructured and re-import you’re opening to otherwise avoidable issues.

            Noz – / @nozurbina

  • Noz Urbina

    There are several tools these days doing DITA in word. Off the top of my head Quark XML Author, Content Technologies DITA Exchange and SimplyXML (although still a relative noob, looks very interesting).

    These have proven an effective in allowing non-technical authors to contribute DITA without knowing it.

    • Tom Johnson

      These DITA Word template solutions appeal to me because so many people are familiar with Word. I did watch the SimplyXML videos and it seems like an intuitive template. These solutions seem more practical than easyDITA if they will sell the templates for a one-time fee rather than charging high-priced monthly fees for usage. Still, everyone must download the specific template and be trained on how to use it. Also, we also have to create the transforms to generate the outputs from these templates.

      • Noz Urbina

        The tools aren’t (usually) templates, but actual applications – plugins, if you will – that sit inside the Word shell and guide behaviours. Templates could be easily made and duplicated, so there would not be much in it for the developer.

        Considered it a ‘stealth’ XML editor. It is leveraging Word, but itself it is its own application. This bridges the familiarity gap and makes users happier to put up or not even notice the underlying (but inevitable) changes that XML editing brings.

        Noz –

        • Tom Johnson

          Yes, these stealth XML editors, as you say, that just use Word as a shell, are perhaps what I want. I’m not sure. For example, SimplyDITA uses the stealth XML editors wrapped in Word. But other collaborative solutions just have users author in Word and then import the Word files. They aren’t stealth XML editors — just regular Word templates. The former I might welcome, the latter not. But I haven’t really used either process much. For all my collaborative authoring, I traditionally use wikis. But my colleagues aren’t so much into wikis as I am.

  • Kaye

    I work at a software company and we are working on a similar problem. Our main issue is getting content from the printed materials (user guides and training manuals) into our online help text and the other way around. Our online help text is integrated into the code of our application, so I am working with our engineers to come up with a way to share content easily between the application and the print.

    To start, we have prioritized the “must-haves” and the “nice to haves.” Our “must-haves” are focused on updating materials in as close to ‘real-time’ as possible and a ‘review-edit’ process between our groups of writers. The “nice to haves” are things like users being able to comment and to stream tutorial videos.

    I’m interested to see what solution you come up with and I’ll keep you posted on how our process is going.

    • Tom Johnson

      It seems like a wiki would do most of these things — real-time editing, a review process, comments, video embedding. The problem with wikis is that they usually don’t store content in a structured format, so you can’t do a whole lot with the output. Wikis do render output to HTML, so perhaps there’s a way to transform that to XML and then transform it, but that seems prone to error and problematic. I sometimes wonder if the long guides that people request are even necessary.

    • AB

      Kaye, what did you guys end up going with?

  • Marcia Johnston

    It’s helpful to hear about software-related solutions, but tools can only go so far toward resolving the issues that Tom’s talking about. I’d like to hear more about processes. Independent of the tool, what processes are people using to support consistency, findability, and reuse?

    • Noz Urbina

      Hi Marcia,

      You are SO preaching to the choir… but, alas, I am totally time strapped today so I tossed off a few product names.

      The important stuff takes far more thought and time to address.

      Noz –

    • Eddie VanArsdall

      I’m responding to Marcia’s question on processes for promoting consistency and findability. For any organization–but especially for large ones like LDS–I recommend tapping into resources who have a solid grounding in building taxonomies. Large organizations typically have people with information science backgrounds among the ranks. Information architects often have such backgrounds, too.

      The creation and development of controlled vocabularies such as thesauri and facets can provide search precision beyond that of machine algorithms. Plenty of tools exist for developing taxonomies, but smart people have to drive them. Many taxonomists start out with a spreadsheet. At the high end, there are cloud-based tools for managing terminology, including Data Harmony and Synaptica.

      • Marcia Johnston

        Thanks, Eddie.

        Excellent insight: “Smart people have to drive them” (taxonomies, controlled vocabularies).

        I’m curious about enforcement. I’ve been in teams where decisions got made about terminology, for example, only to be disregarded as writers continued using whatever terms came to them. As a writer myself, I know how hard it is to keep a long list of controlled terms in mind while focusing on a message. Seems impossible to hope to achieve consistency across multiple human brains, no matter how hard you wave a style guide or terminology list in front of them.

        Short of hiring editors, how do you get content developers to keep their content consistent (and findable) in all the ways that matter? And how do you ensure that the structures created by those “smart people” get implemented properly?

        • Tom Johnson

          We have so many different products, I’m not sure a taxonomy that provides standard terms would be that useful. We have a style guide that lists preferred names and such, but I don’t see how you can enforce a taxonomy in a culture of mass-collaboration.

      • Tom Johnson

        Thanks for bringing up taxonomies. I continually hear this in content strategy discussions, and I feel like it should inform our enterprise help strategy, but I’m not sure how to implement them. We won’t have one giant help database of information or sites. Rather, we’ll have probably 100+ separate help files for 100+ different applications, without the need to provide search that spans the whole database. As I understand it, Mark Logic allows you to create multiple instances of databases, so each application could have its own database. Does this mean we would need to create taxonomies for every database? Or would taxonomies no longer be necessary because the information is segmented into its own database; therefore semantically the topics probably won’t overlap with other similar terms?

        • Noz Urbina

          Hi Tom, do your products never get used by the same user? That is, does each end user only ever install one product, never in conjunction with the other 99+?

          If there’s ever any audience overlap, you should look at taxonomy. Frankly, even if there isn’t today you should look at taxonomy anyway because who knows what the future will bring? Taxonomy is very powerful and useful for a plethora of reasons.

          What if two products one day get integrated and packaged as one? What if 4 become a suite? What if one splits in half and two different writing teams in two locations have to maintain their ‘bits’, but have assurance things go back together when the product is sold in its original larger configuration. The engineering and prodman teams will do everything the can to get the most revenue per app, and that can create downstream work for you.

          Also take more blue-sky thinking like for example, SEO – not really your ‘problem’ in tech comms, but lots of people google for terms when looking for solutions, and as your help goes online, if your terms match what people put into google when looking for a solution, your content goes up in rank.

          Also, just being able to speak the same language is just a useful thing, even if it just aids communications and collaborations in your newly formed cross-dept tech comms group.

          When it comes to enforcing it, it doesn’t happen in the database. Imaging a wagon-wheel. At the hub is the database, connected by network spokes to the wheel itself, which is where all the content creators and reviewers sit at their desks. Taxonomy / terminology control happens when the content is in the user’s hands. It’s like spell checking. You would never write something, then put it on the server and trust that a computer would spell-check it and choose the proper corrections for you. Same with terminology/taxonomy.

          You edit, then you (or someone else) validates terms and metadata, and then the content moves to the next stage in the workflow. If you aren’t the one doing validation, your copy gets put back in the repository in one workflow state and then when it’s checked, it’s released to the next one.

          In terms of automatic enforcement/assistance with enforcement, there are tools like Acrolinx, HyperSTE, and the like which operate as highly configured XML spell-checkers on crack that can help you with all sorts content correction in your document.

          Noz –

          • Tom Johnson

            Sometimes I feel comfortable in a knowledge domain, and other times I realize how little I know. With the taxonomy, as I understand it, tools such as Acrolinx enforce rules so that you don’t flip around the same terms with synonyms etc. The rules can be more sophisticated to enforce certain styles and formatting. That would be a good tool to implement — some day.

            I guess I don’t see how important it is to be 100% consistent across the enterprise with our terms, especially if this exactness creates a strong learning curve to dig into a style guide. I’m more interested in a tool that provides tagging for a real-time folksonomy, regardless of the discrepancies. Over time the more common terms would win out.

    • Tom Johnson

      I know processes are important too. But the process is dependent on the tool as well. If I have a collaborative, in-browser tool for authoring, that will lead to a different process than an offline Word template. We have defined our requirements and have a decent grasp on our process, so we are starting to explore technical solutions that will accommodate these requirements and the process.

  • Greg Woolf

    Not that it meets all your requirements, but we use a pretty helpful tool called JIVE.

    • Tom Johnson

      Greg, can you share more about what JIVE is and does? Does it just track social media? Sounds interesting. Are there any applications to more traditional tech writing with it?

  • Casey Jordan


    Great job articulating a common but complex problem. This post especially interesting since I have been part of a team that has been working to solve many of these issues for the past few years.

    The culmination of that work is a web-based software platform called easyDITA ( which has unique and non-technical solutions to nearly everything you mentioned.

    Without going into too much detail:

    – Standards compliant WYSIWYG DITA editor
    – Pre-configured modes/roles for reviewers and contributors
    – Simplified content re-use (search cms and instantly re-use content)
    – Native XML content management + search and discovery
    – Built in drag and drop DITA map editor and publishing

    Our current users have found it to significantly simplify and speed up contribution and review processes. Especially for the non-technical or users who are geographically separated.

    @Marcia & @Noz – Good point. I would tend to agree that understanding the process is the key to making the technology work. It has been a goal of mine to (in my spare time) catalogue white-papers and studies around collaboration processes related to DITA content. If you know of any good resources I’d love to know about them.



    • Tom Johnson

      Casey, easyDITA looks really promising. It does seem to support all of our requirements. We’re not so eager to lock ourselves into a $5,000 a month usage contract, though. I’m sure we’ll have this conversation next week when you give us a demo, but we’re wondering what the pricing model is for installing the software on our own servers. I do have a lot more questions, too, such as what some sample outputs look like (or is that something we configure on our own?). I wish your launch date had already come, as we’re eager to try out the easyDITA solution.

  • Christine Astle

    In my opinion, you fundamentally need two things: structured, topic-based authoring and a component content management system.

    The structure doesn’t have to be DITA (there are others or you could go custom) but it should be enforced, thereby forcing consistency. Also, the structure doesn’t have to be visible to contributors; if you have the know-how in your organization, you could build an interface to add different types of content to the system.

    As well, to really have pieces that are reusable, consistent, etc., I think these systems need gatekeepers/curators, who review what goes into the system to ensure it meets certain guidelines.

    Other than that, I can’t help you much since we’re in the pre-adoption phase of a corporate system.

    • Marcia Johnston

      Christine, your comment — “… these systems need gatekeepers/curators, who review what goes into the system to ensure it meets certain guidelines” — gets to my question about editors. Can anyone speak to experience with such a role in action?

      • Noz Urbina

        I have used Schlumberger as an example in a few conference presentations. I would have to dig around a bit to find them, so let me know if you want me to – anyway: Schlumberger created a ‘matrix’ review process where different types of subject matter experts reviewed component content with different ‘eyes’ such that by the end of the workflow it had been checked for legal, structural, stylistic, and technical quality.

        When we’re laying out XML-based component management processes we often suggest that one or two resources (or more, depending on the team size and structure) get focussed editorial control of application of XML business rules and metadata. CMS is heavily metadata reliant and having some gate-keepers as part of the release control aids change management. Train a small number of people to the teeth on the guidelines and have them be the local support for their peers as they adjust to the new tools/guidelines. After a while the new process beds in, and the editors can move on to other specialisms or go back to a heavier writing load.

        Noz –

    • Tom Johnson

      We do have a lot of in-house experts that could assist with a solution. We actually have a team that built a software application similar to WordPress/Joomla but uses Mark Logic as a database and stores all the content in XML. Ideally, we could author in this and then create some transforms to generate the printed material and other formats. Then we wouldn’t be locked into a long-term fee with an application.

  • Kristi

    I feel compelled to congratulate you on having the opportunity to address this in such a comprehensive way!

    I don’t have a tool recommendation, but I am curious about some things:

    How did you all arrive at the requirements? Were some people from each of the stakeholder groups involved, or will you validate these with them at some later point?
    What’s the level of enthusiasm vs. concern for learning new tools and processes?
    I’m getting the impression that you must have some kind of executive buy in on this to be confident that you’re moving forward at an enterprise level. Would you mind talking a little about how you accomplished that?

    What a great project!

    • Tom Johnson

      We do have buy-in from senior leaders, but one thing is missing: we need to rally the tribes (disparate writing groups) together and ensure we have buy-in from them. That’s probably a key step in finding a solution that makes everyone happy. But we’re confident that we’ve articulated the pain points and the requirements that are common to most everyone.

      How did we get buy-in? A recent reorg changed our structure. Rather than being embedded individually in each department, we’re now a shared service across the entire organization. We’ve been seeing pockets of writers appear all over for years and have been frustrated by it. Our new manager is encouraging us to define how we do help, and this is a perfect opportunity to define an approach that solves the problem for the entire organization.

      • Noz Urbina

        Mazeltov! Reorganisation into a corporate service is a great step in the process evolution of the tech comms group. Many writers argue for complete integration into the product development process, but in fact, you want to keep together. There’s safety, sanity and resource in numbers!

        • Tom Johnson

          I lived the development-team-embedded model for three years. For tech writers, it’s isolating and lonely. We could never build enough camaraderie among our team to formulate standards. Also, tech writers bounce around from project to project anyway, so it’s not so critical to stay embedded in a dev team because (at least where I work) most projects are small. If the projects were longer and more involved, yeah, I could see a case. But I’m ready for a switch to sit among other tech writing professionals.

  • Eddie VanArsdall

    Tom, I agree with those commenters who emphasize process first and tool selection second. When you get to the tool selection stage, I recommend that you look into open source solutions.

    My project serves a large government entity with many of the same issues and requirements that your organization has. We are implementing the Alfresco ECMS this year, and it shows great promise. I attended an event in DC last month where I was able to see some case studies and learn more about the underlying technology.

    I’m just using Alfresco as an example. There are plenty of open source solutions out there. If the idea of open source scares your leadership, remind them that plenty of consulting companies provide paid support and services for the various products. I know because many of their representatives gave me their business cards at the recent event.

    You may want to subscribe to CMS Wire ( as a means of seeing what’s out there. Meanwhile, lay your foundation: examine your processes, conceptualize workflow scenarios, and create a content governance board.

    Sounds simple, right? 😉


    • Tom Johnson

      Interesting. Alfresco ECMS? I have heard of Alfresco and know it’s a highly popular open source CMS. I’m curious whether it would just act as a CMS or whether it could also offer some kind of multi-channel publishing. When you create content in Alfresco, how do you get that same content out for printed deliverables? How do you organize the online help when you have 500 topics? Is there an existing example of a site with help documentation on Alfresco, or would this be an unconventional use of the platform?

      I do like the idea of using web CMS tools for help content. Help content too frequently looks antiquated and 1990ish. We need to join the web with function and style and interactivity. But usually when we make that step, we lose some of the documentation features that we need, such as conditional publishing, multiple outputs, etc.

      • Casey Jordan

        One of the things that we have seen emerging is the use of a mash-up of systems.

        For instance a common setup would be something like:

        – Component Content Management system (CCMS) to manage re-use and single source publishing, authoring and review. (Ideally native XML and using a standard like DITA, DocBook, S1000D etc).
        – Published Deliverables are pushed or synchronised with CMS/ECM/LMS which manages delivery to end user. (Typically Alfresco, Sharepoint, or Portal/Wiki/Wordpress)
        – Optionally the use of a Digital Asset Management system which would integrate with both CCMS and ECM for DRM.

        With newer systems integration like this is fairly easy via standards like REST, XMLRPC, CMIS, SOAP etc.

        This is an interesting progression away from large expensive all-encompassing systems, to tightly integrated and highly focused niche solutions.

        It eliminates the silo, and allows business units to exact more control over access, work flow and how/where processes like review happen.

      • Noz Urbina

        As Casey said, there’s no reason to lose the power when you got to CMS, just don’t got web CMS.

        You’ve stepped in one of the most common CMS gopher-holes here:

        “I’m curious whether it would just act as a CMS or whether it could also offer some kind of multi-channel publishing.”

        It is not in the interest of serious CMS vendors to become publishing tool vendors. Although some exceptions apply and some instances, like Author-it or, chose/choose to go for an integrated package approach, the Alfresco’s, SharePoints, Trisoft, Ixiasoft, XDocs and so forth packages are NOT themselves the tool that creates the output. You may think you want it, but you don’t. The reason they don’t bother becoming the output tool is because output is very particular.

        We share many features when it comes to our management process, but there’s also room for some flexibility as to how it gets managed as longs as however it works, it solves the business need. When it comes to how it *looks* and gets delivered, we’re incredibly exacting vis-a-vis the result, and we all want it fitting into our performance, ease of use and budget parameters. There’s also incredible ‘loyalty’ issues of people who love their InDesign, Quark Xpress, Robohelp, FrameMaker, Word (as a pubs tool, yes), etc.etc.etc.

        As such, it’s not in the interests of a CMS vendor to try and please everyone with their technology. Instead, it’s far more effective for them to allow integrations to various tools and give the customer choice. There’s a niche for the ‘all in ones’, but it shouldn’t be a parameter to go by – if you’re talking about a solution of the scale you seem to be, then as Casey said, integrating a CCMS with an existing infrastructure is far more flexible and creates less of change management and political nightmare.

        Noz –

        • Noz Urbina

          You probably know by know I tend to be rather curt (read: am a big mouthed jerk); so I’m sorry for saying ‘you may think you do but you don’t.’ Far more polite would be: I think that if you ask around, you’ll find that there’s a) many arguements for not buying a single package b) many very good packages that should not have points taken off for not being publishing tools.

          I discuss with Prod Managers from CMS companies on a regular basis. Most feel feel it’s reinventing a wheel, which they’ll most probably get yelled at for having reinvented by the very people they reinvented it for, because it’s not the wheel *they* wanted.

          • Tom Johnson

            I feel so ignorant in this realm. All my career, I’ve either worked in a centralized authoring team, as a lone writer, or as a semi-lone writer. Making this transition to an enterprise-wide approach for collaborative authoring is tough. What’s crazy is that we’re trying to come up with an approach that we currently don’t have a pressing need for. I keep saying that we want to enable people across the enterprise to author, but I have a difficult time getting anyone to even make edits on a wiki. We have the if-you-build-it-they-will-come mentality, I guess.

            Thanks for clarifying the CMS publishing conundrum for me. I didn’t realize that serious content management systems didn’t concern themselves with output. Looking at easyDITA, I see that it offers WordPress as an output. That looks interesting. Really? I mean, how the heck does a tool do that without some serious programming to make that integration happen?

            It’s all fine to disregard the output, but then that leaves us to become XSL programmers to customize our outputs, or to hire someone to do it for us. Attractive output is hugely important to us, both for customer buy-in as well as buy-in from other dept. writers, so it’s hard to minimize this element.

            By the way, thanks for your critical attention on this thread. I appreciate it.

          • Casey Jordan

            @Noz, not only are you spot on with your advice but you cracked me up along the way.

            @Tom in response to “but I have a difficult time getting anyone to even make edits on a wiki”:

            One of the things that we are experimenting with is a way to add game logic to the problem of enterprise authoring.

            For instance, in easyDITA tickets can be issued that automatically send out email invites for people to come contribute or review documents. The ticket then tracks the whole process from issuing to completion.

            Users can then gain “Experience” or “Badges” based on how many tickets they completed, or how quickly they completed them or how accurately (IE: the ticket did not have to be re-opened). Other users could even rate the process using a star system.

            This can be extended even further by looking at how authors content is re-used. Authors which get a lot of re-use from their content would get a badge for content re-use quality. And, since easyDITA keeps an record of all commits and reviews, authors who’s content had a low threshold of review marks would get another badge for “Initial content quality”.

            The ideas are endless but using social systems like this makes the whole process fun and encourages people from all departments/community to participate.



  • Val Swisher

    I know I’m late to this discussion, my apologies. First off – I love all of the great information that this discussion has brought forth. Thank you for putting this important topic out there for us all to comment on.

    I wanted to take a little moment to discuss Acrolinx IQ and why I think it should be part of your solution. Acrolinx is a very powerful tool that is used by companies of all sizes to:

    – Standardize your terminology across all of your departments and silos.
    – Enforce your brand standards, ensuring proper use of trademarks, servicemarks, and so on.
    – Enforce adherence to your company’s style and grammar rules.
    – Ensure consistency of like-meaning sentences – in other words, make sure that you (meaning everyone in the company) says the same thing, the same way, every time you say it.
    – Provide objective reporting, metrics, and tracking so that you can monitor how folks are doing.

    It is a very powerful tool that is used by most Fortune 100 companies including IBM, Cisco, Adobe,

  • Val Swisher

    I know I’m late to this discussion, my apologies. First off – I love all of the great information that this discussion has brought forth. Thank you for putting this important topic out there for us all to comment on.

    I wanted to take a little moment to discuss Acrolinx IQ and why I think it should be part of your solution. Acrolinx is a very powerful tool that is used by companies of all sizes to:

    – Standardize your terminology across all of your departments and silos.
    – Enforce your brand standards, ensuring proper use of trademarks, servicemarks, and so on.
    – Enforce adherence to your company’s style and grammar rules.
    – Ensure consistency of like-meaning sentences – in other words, make sure that you (meaning everyone in the company) says the same thing, the same way, every time you say it.
    – Provide objective reporting, metrics, and tracking so that you can monitor how folks are doing.

    It is a very powerful tool that is used by most Fortune 100 companies including IBM, Cisco, Adobe, John Deere, Medtronics, and many others.

    Having a terminology list and a style guide is a great start. Getting your writers to use it is another story all together. Most people do not have the time or inclination to constantly look things up in the style guide. Having a tool where your style guide is programmed in and always available is a much better solution.

    It is great to repurpose content using DITA/XML solutions. Write once, use many is an important content strategy. If you are planning on reusing content, it is even more important that your content be accurate, consistent, and in-brand. Otherwise, you are simply perpetuating a problem from the start. This is exponentially true if you are localizing and translating your content.

    Acrolinx allows non-authors to follow the same terminology use and style consistency as authors. The software is extremely easy to use – it is a plug-in to all of the most popular authoring tools, including Arbortext, Xmetal, FrameMaker, Word, InDesign, Author-IT, even Excel and PowerPoint.

    I hope this helps. (and for full disclosure, my company is an authorized reseller and service provider for Acrolinx, so I am naturally biased. :-) )

  • Pingback: Update on the Search for Enterprise Authoring | I'd Rather Be Writing()

  • B Noz Urbina

    @Tom – This conversation is getting deeper than the stylesheet allows, so I’ll just respond here:

    “WordPress as an output. That looks interesting. Really? I mean, how the heck does a tool do that without some serious programming to make that integration happen?”

    FAR less then one might think. All blogs offer a simple publication API. A good programmer could add blog publishing from just about anything to any worthwhile blog platform in weekend if they were bored.

    “We have the if-you-build-it-they-will-come mentality, I guess.”


    Warning! Warning!

    If you build it, they will not come. They may even get mildy annoyed you built yet another collaboration system they’re expected to work with and contribute to (besides the WIKI and various others surely knocking about).

    Emma Hamer, a wise, sage and brutally upfront woman, said at a past X-Pubs Conference (now Congility 2011 “Process change = cultural change”. The reason your WIKI isn’t working is the same reason your new system will struggle. If you don’t address people and process, technology is useless (that’s a general statemet not a finger pointed at your efforts): An infinite number of teams have launched their new centralised, collaborative, syngeristic whatever, with the rallying cry: “It’s not a WIKI, it’s a WITTI!”, or whatever they felt was significant but was otherwise underwhelming/uninteresting to their intended collaborators.

    You need to address why they aren’t participating as a primary concern. Have you laid out what’s in it for them other than the satisfaction of collaboration (try saying that with a straight face). I’ve had many customers ask ‘So you’re putting this thing in. Great. What else are you going to take away while you’re at it?’. There are too many ways to collaborate in just about every organisation. Be sensitive to the motivations of your intended SMEs.

    @Casey – Thanks! I would agree that game mentality features are very helpful. We’ve been suggesting such things to clients but until I read your post I never clicked that they were video-game like. I’m feeling a bit stupid now because the connection is fairly obvious.

    I dont know if users (especially in Europe) will take to the direct reference to gaming. Do you put the features in and explain them or do you actually sometimes say outright ‘It’s like a game’? I’d be curious as to what user feedback you get.

    Noz – / @nozurbina

    • Casey Jordan


      Good stuff. I really like how you stress culture change being tied so closely with process change. It is a tough thing to get right. The big way that we are trying to help organizations with this is to build tools that aren’t focused on simply “collaborating on data” but are focused on strengthening relationships. Whether that is the relationship between the Tech writer and the SME or the SME and the customer. We’re only just starting to explore this and its just a small piece of the solution, but it can significantly help.

      “Do you put the features in and explain them or do you actually sometimes say outright ‘It’s like a game’? I’d be curious as to what user feedback you get.”

      We are still only throwing this around as a prototype, but I anticipate that I will not be referenced to as a game, possibly referred to as some sort of metric depending on the audience.

      It originally started out as an idea to help people walk through the trial process when they first start using the software (Similar to how linkedin helps you complete your profile when you first start). So an interesting idea we had would be to have an “easyDITA IQ”. You get 5 IQ points for filling out your profile, 5 IQ points for creating your first topic, etc etc. Completing the whole starting process would get you up to an IQ of 100. Then the badges could follow based on computing your points in various categories (Authoring, Collaboration, Review, Re-use) etc. The social aspect of it could get very sophisticated with the ability to wager points against getting a task done, give praise points, but there is fine line to where this could become counter productive.

      I won’t blab on about it here because its somewhat off topic, but I’d like to get your opinion on it when we have a working prototype, esp. in reference to the European markets.



      • Tom Johnson

        Sounds like an interesting strategy. I recommend keeping it simple. Other sites have similar points-based strategies (for example, Perhaps you could incentivize the contributors not only with points and banners, but also by increasing their rights within the system as they gain more points.

  • Gabriel Boczar


  • Caterina Pryde

    In response to your original post, I think you might want to look at Flare. I don’t usually recommend it, because my clients generally need to have the ability to update and regenerate without tech writers. As an enterprise tool, with professionals, I believe it would be a good option. I’ve included a link to a good article about possible tools.

    • Tom Johnson

      Thanks Caterina. Flare is our current tool, so we were looking to see if it would scale to the enterprise. I haven’t written about this yet, but we mostly decided to keep using Flare, because n0 other solution jumped out at us in a convincing way. I appreciate your advice about our challenge.

  • The Art Of War

    Hi, I was just doing some research for a new video I’m going to make and wound up here. Looks like you have some interesting stuff. . . I’m doing some translations of stuff nobody has seen before and putting it up so feel free to stop by and check it out. I think it might be interesting to you. :)

  • Brandblusser

    Hello, your blog does not show correctly on the ipad2. Could you fix this?

  • Megan

    Hey there, that is a really good post. Sincerely enjoyed reading that. Later

  • rocket spanish course free download

    I do not understand how people can read this and not think “genius alert”. Great work. I’ll keep coming back to read even more.

  • Debroah Santisteban

    Admin please like my fan page

  • Sam

    |||||||||| Private Comment ||||||||| Sorry I can’t see contact form on your blog so I am writing here. Your blog is cool, I am also a blogger & SEO guy. I would like you to send me friend request on facebook, We will share our experiences with each other. Thank you! See you there :)

  • MM1772

    I have a different enterprise help problem. I’m documenting the policies and corporate practices around using Microsoft Dynamics GP. It has its own help, and it has multiple third-party plug-ins that have THEIR own help. If the user is in the product and wants to know how to enter an invoice, but doesn’t realize or remember that we’re using a third-party product for the billing portion, and presses F1, we have a problem.

    Are you dealing with anything like that? How are you handling it?