Why Help Authoring Tools Will Fade

I read a blog post the other day that I can’t stop thinking about. In the Myth of Single Sourcing, Michael Hiatt writes,

The main issue for me is between authoring static in-house documents using single-sourcing methods before publishing, or capturing information sources dynamically after publishing from online social networks, linked data sources, and knowledge mashups.

The myth of single-source authoring is that it actually has a life in the future and remains a viable goal for many information developers. With so many mega-trends against it—such as the belief that static authoring from a single vantage point from a single author paid by a single organization is a workable system—seems ludicrous. Instead, we should be looking to capture, sequence, and give context to the wealth of rich content already published in context from the Web. Collaborating with the many subject experts, authors, videographers, bloggers, tweeters, and writers coming together on the Web with shared interests will be powerful if it can be harnessed.

The myth of single sourcing

The myth of single sourcing

Michael undercuts the idea that you can create help from a single author working from a single perspective in a single point in the organization. To add to this scenario, usually that author is an outsider to both the environment and business processes he or she is documenting. Further, the author usually moves on to another project as soon as the software is released.

This morning I had a meeting downtown at SLC headquarters. I’ve become accustomed to wearing business casual clothes to work, but at headquarters, I have to wear a full suit because that’s the dress code. In an early morning meeting, I listened to several department leads explain my new project. It would involve extensive knowledge of cataloging and archiving techniques, a robust off-the-shelf system that had been customized, five main divisions or modules to conquer, each with their own resource leads, about 200 constantly rotating users complementing a core group of specialists, and an aggressive time frame.

As I listened and glanced through the archiving and cataloging procedures (did you know there’s a Society of American Archivists, and that they have in-depth protocols for how things should be done?), I realized that learning the business process surrounding the application would require complete immersion in each of the five divisions over the course of several months. I would need to constantly interview subject matter experts, participate in the actual archiving and cataloging processes, and make sure everything I created was reviewed, checked, and edited for accuracy by each of the five major subject matter experts. The end documentation would probably be several hundred pages for the initial release.

Keep in mind that I have about three other concurrent projects that I’m working on with approaching deadlines (unlike developers, no writer ever gets to work on just one project). Could I pull something together by February/March?

At this point, Michael’s post was resonating like a blinking banner in my head. Authoring from a single vantage point from a single author is … ludicrous.

Even if I were to import existing documents and materials from SMEs into a HAT, who would own it after I finished? Would I become a permanent installation in the department, constantly processing updates, verifying instructional clarity, addressing gaps and making edits? If not, would the documentation become stale six months after release, when SMEs decided to change their business processes?

In an organization where several thousand people have only a handful of actual technical writers, we’re a scarce resource. I bounce from project to project, like a little visiting angel (or devil) who works a little documentation magic and then moves on.

Another group on my team is tackling an even larger project, one that involves complex financials. They’re using Flare. They started using X-Edit and entitled a handful of business writers to contribute content with it, but X-Edit proved either too buggy or unworkable. Now the business SMEs are passing Word documents to the guys with Flare, who are inputting the information into the HAT. After release, the idea is to have the business department own the documentation and continue making updates using Flare. It will be interesting to see if they actually do it.

In thinking about these robust software scenarios, where products require extensive knowledge of business processes, have elaborate interfaces with hundreds of possible tasks, and are run by dozens of specialists constantly refining their own business processes, is there any other platform besides a wiki that can actually work? What else can you use to enable 10 different authors to make simultaneous updates, to maintain the documentation after the release? How else can you infuse the documentation with the intricacies of a department’s business processes?

Using any of the standard authoring tools — Flare, RoboHelp, Author-It, Doc-to-Help — leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.

Madcap Flare Adobe Robohelp

This entry was posted in general, web 2.0 on by .

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, DITA, and more. If you're trying to keep up to date about the field of technical communication, subscribe to my blog. Email

21 thoughts on “Why Help Authoring Tools Will Fade

  1. Pingback:   Musings about what’s really important by Communications from DMN

  2. Anne Gentle

    Couldn’t have said it better myself, Tom. And I’m looking forward to hearing more from Michael! I have had that epiphany several times over the years – no single person can do this topic justice. :) Collaborative authoring, community documentation, here we come.

    Reply
  3. Rhonda

    Nice post, Tom. And food for more thought on this topic (I’ve been thinking about it for a while now, esp. as I’m working in a very large global corporate where Word is the only common denominator for creating and maintaining docs.)

    BTW, in addition to the Society of Archivists, there are all the various national and state Library Associations with special interest groups for cataloging, then there are the various cataloging and classification systems, subject heading groups etc. etc. (I used to be a librarian in a previous career!)

    Reply
  4. Pingback: Technical writers, web writers, jobs, and employers | just write click

  5. Elizabeth John

    What you described is an everyday scenario for most writers, though we may have the passion to learn everything around a given product we will never have the time to pursue all aspects of it or be in a position to constantly update information. I think this does tie in into what this article talks about in terms of content curators (http://socialmediatoday.com/SMC/131472). Wikis maybe a solution but even information posted on wikis need to be monitored and base lined. I feel the most important improvement we can make is “to close the loop”, meaning, when publication from a single author single point is published, tech writers must take it on themselves to involve in the community of users; internal and external. They could start a wiki/video site/twitter/forums/etc, where they are aware of the changing dynamics of the product, complaints, suggestions, needs of the customer, etc. This will provide the feedback required to improve the next version of static content published. Another aspect that writers need to keep in mind is power of e-learning. You still need to create content but the presentation need not be pages and pages of text rather videos/e-learning and simple how to’s. In this case SME’s who ideally are not fond of putting things to paper may deliver effective training by just recording some simple demos, which can be further standardized and published by writers.

    Reply
  6. Eddie VanArsdall

    I agree that the direction of user assistance is certainly changing and will continue to change, but I’m skeptical of blanket prophetic claims. Single sourcing is an end-point publishing process designed to make one content source available in multiple formats. It is not always the result of “a single author working from a single perspective in a single point in the organization.” If that’s the case, then that’s how the organization has chosen to use it. At other organizations, one author may simply be responsible for the final build of content that has been collaboratively developed.

    I have worked on many teams where authors and SMEs truly collaborate to produce quality content. When we’re ready to publish, we use single sourcing so that our information consumers can have the consolidated content in their preferred formats. If they prefer to see only pieces of content, it is often also available on wikis and forums. The content lives on and can be massaged, but the single-sourced version remains available as a snapshot.

    I also sense that many who are declaring the death of single sourcing assume that all technical writing supports software and consumer products. I live and work in a geographic area (Washington, DC) where we often produce highly regulated content related to government policy, defense, aviation, and scientific research. Authors and SMEs collaborate during the information development stage, but single sourcing can be vital at the publishing stage. One agency that I worked with creates searchable intranet sites that are basically huge help systems designed for policy analysts and actuaries. PDF versions are also available. Those sites are often created with standard HATs. Once the information is published, it’s not open for discussion or editing until the next review cycle.

    Even if HATs as we know them die, I believe that some form of CMS will supplant them in the business environment. Maybe the model CMS will be open source and enable highly collaborative workflows. Regardless, although the fed is experimenting with social media, I doubt that we’ll see policy aggregated from wikis, blogs, and tweets anytime soon.

    Reply
    1. Tom Johnson

      Eddie, thanks for your comment. I agree that especially in highly regulated industries, a formal set of documentation at a specific snapshot is necessary, with only periodic reviews. I’ve never worked with that restraint. Usually the need has been to apply immediate updates to the content, rather than lock the content down from updates.

      You mentioned that SME’s can collaborate to produce the quality content and then use a single-sourcing HAT to publish the content. However, I think that gets difficult technically. If you collaborate either via Word, a wiki, SharePoint, or X-Edit, and then pass on that finished information to a single-sourcing HAT, how do you make updates to the content after publishing the single-sourced information? Is that something you review at a periodic review cycle, creating new documents that highlight excerpts that need alteration?

      It seems easier to keep the content in one source, rather than transferring it to another tool, and so forth. But you make a good point.

      Reply
  7. Paul Trotter

    I think neither option is workable or practical.

    Having a single author does not offer enough perspective, subject knowledge or manpower, but leaving it up to the cloud or crowd to create unstructured dribble and try to cobble that together into a cohesive, sensible document with some ‘magic’ mash-up tool is just as… ludicrous.

    While crowd sourcing and social media are very effective in a project like Wikipedia, most of the content produced in support of sale, operation, and maintenance of complex products, policy and procedure, or regulatory compliance needs to be written by professionals in a structured manner using a controlled process and system.

    What we need to resolve this problem is a system that allows professional writers to create the structure and controls around the content, but also allows everyday business users to easily contribute without technical tools knowledge.

    Now for my plug… while Author-it may have started off life as a HAT, to call it that now is gross understatement. Over the years Author-it has evolved and matured into a comprehensive authoring, management, and publishing solution for the whole enterprise. We now refer to Author-it as an Enterprise Authoring Platform.

    The way we have addressed this problem is to provide a full browser based Web 2.0 interface to Author-it which is specifically designed to be used by everyday business users to contribute their expertise and knowledge directly from any location, with no software to install. It is easier to use than a wiki (no complex markup to learn) and just as accessible.

    We have been selling Author-it Live for several years now and it is very popular for the exact reasons that are discussed. If you want more information on it just take a look at our website http://www.author-it.com/index.php?page=webauthoring.

    So while HATs may fade, I believe that a new generation of technology will take over… the Enterprise Authoring Platform (EAP).

    Reply
    1. Tom Johnson

      Paul, thanks for your comment and insight into the situation. I’ve heard of Author-it Live, but I didn’t know much about it. Your comment clarifies how it works and addresses the problem I described. I’m very much in agreement when you say,

      What we need to resolve this problem is a system that allows professional writers to create the structure and controls around the content, but also allows everyday business users to easily contribute without technical tools knowledge.

      I don’t think that non-writers will suddenly create books of documentation simply because they have the tools to do so. However, they will make small edits, little updates, add a little here and there. The fact that Author-it Live allows that is pretty cool.

      I visited the link you sent me, but I wanted to see more information about it. Do you have a screencast demo or more extensive visuals? I also didn’t see anything about pricing for Author-it Live.

      Reply
      1. Paul Trotter

        Hi Tom,

        You can find more detailed information about Author-it Live on our Knowledge Center http://kc.author-it.com/#b7868.

        Author-it Live is sold in both Small Business and Enterprise editions. The pricing starts at around US$15K. It is all installed on your own servers in-house. Hosted options are available if necessary.

        We have just launched the SBS edition, see more information on my blog http://author-it.com/103fjq

        BTW, teh Author-it Knowledge Center is all powered by a new Author-it product being released very soon called Author-it Aspect. It is a Dynamic Delivery Platform, for more info see:
        http://www.author-it.com/index.php?page=latestproducts
        http://kc.author-it.com/#b11510

        If anyone wants a demo just contact our sales team sales@author-it.com.

        Paul

        Reply
  8. Ivan Walsh

    Hi Tom,

    Who benefits?

    Vendors & consultants benefit by selling single-source apps and other services. They will find their corner and slow down any shift away from these platforms.

    Technical writers/tech comms folks may less influence in these matters. At least that’s my experience.

    So, while I (mostly) agree with Michael’s argument, I think the shift only comes when the vendors and others higher up the food chain stand to benefit.

    Regards,

    Ivan

    Reply
    1. Tom Johnson

      Ivan,

      You bring up a good point. Vendors will hardly embrace and promote solutions that won’t bring their companies profits in some way. I think most vendors, however, would always advocate that the tools they create are for the benefit of the industry, though maybe not applicable to every situation. And it’s true. An open-source wiki solution wouldn’t work for a lot of industries and situations. In some cases, you need an authoring tool that helps you maintain a tightly controlled structure to each topic.

      Reply
  9. Pingback: Technical Writing News Nov 27th - Free Newsletter | I Heart Tech Docs, Ivan Walsh, Technical Writer

  10. Neil Perlin

    I don’t agree that help authoring tools (HATs) will fade away; I do think they’re going to continue to change just as they’ve been doing for years.

    First of all, I’d argue that the term “help authoring tool” is just a convenient way of referring to tools like RoboHelp, Doc-To-Help, Flare, AuthorIT, etc., but also a term that can limit how we think about these tools. (It’s telling that MadCap did not use the term “help” when they named Flare.)

    Functionally, these tools went far past “help” authoring years ago. I’ve personally been using them since the early 1990s to create online books, tutorials, marketing materials, etc., as well as “help.”

    We’ve also seen the tools expand their feature sets for years, adding point-and-click options for features that once required hand-coding in the source files. We’re seeing this extension again as the tools start supporting DITA. I *am* surprised that the tools haven’t yet added collaborative authoring features, but I expect to see such features in forthcoming releases.

    Regards,
    Neil

    Reply
  11. Kevin Amery

    Tom,

    I think you’re overstating things when you say “unlike developers, no writer ever gets to work on just one project” – that’s exactly what I do here. Of course, the main difference probably is that I’m a “captive” tech writer rather than a free lancer. I’ve been working with the same company for three years now, and I work on the development direction and testing of our product as well as documenting it. At this point, for about 95% of the product I’m my own SME because I know it as well as anyone else in the organization.

    I think what’s “ludicrous” really is the idea that someone can swoop in at the end of a major project and produce detailed documentation for it, then swoop off to a completely different project. If you want to document anything effectively you need to know it, and you can’t learn something enormous to that level of detail in a few weeks. The problem isn’t the tools or the interactiveness of the workflow – the problem is the “outsourcing” business model for something that requires that degree of detailed knowledge.

    Reply
    1. Derek Warren

      I agree with you, Kevin. In fourteen years of writing documentation, I have had similar experiences to yours. I had been assigned specific projects–sometimes a few at a time–but always assigned as THE writer resource and usually assigned early enough in the project that I had time to immerse myself in it. I think you hit the nail on the head: “I think what’s ‘ludicrous’ really is the idea that someone can swoop in at the end of a major project and produce detailed documentation for it….” And yet, this is precisely how the organization works where Tom and I are both employed. In fact, when I first arrived here 6 months ago and pitched the value of involving technical writers in defining product terminology and writing UI texts, I had sold the general manager but was quickly executed by the lead product manager who insisted that the only place for technical writers was in the final hours of a project, after the design work was complete and development in it’s final stages of completion. So I’m suggesting that whether you empower a community of SMEs to write the content and the tech writer to do clean-up and production, or work as THE writer resource depends on the culture where you live and it’s willingness to adopt new processes. The project Tom referred to in his blog is the project to which I was assigned. I can only say that almost everything being done on the project has gone completely counter to my project plan (also a cultural issue). And yet the same project plan pitched to any of my prior corporate employers would have worked just fine. Thanks for your comments.

      Reply
      1. Tom Johnson

        Derek, thanks for joining the conversation. I think we need to educate project managers more, because with some projects I’m on, they do bring me in early (and others don’t). One time I was brought in so early they hadn’t even determined what type of database to use. I said I’d check back in a month or so.

        I agree that it takes a nimble tech writer to swoop in at the last minute and provide comprehensive documentation. On the other hand, when you approach a project at the end, without a history of meetings, planning, discussions, bug reviews, iterations, and so on, then you more likely approach the project as a new user. You can’t see a project with fresh eyes when you’ve been involved in it from the beginning.

        Reply
  12. Pingback: Destillat KW49-2009 | duetsch.info - GNU/Linux, Open Source, Softwareentwicklung, Selbstmanagement, Vim ...

  13. Bonnie Kern

    Single-sourcing is a strategy, a methodology for generating multiple outputs from a single source of content, regardless of the number of technical writers involved.

    Applying conditions to the content supports generating documentation for multiple products, platforms, and conditions, and the same content source can be used to generate content for various distributions including online and in printed form.

    Single-sourcing allows you to enforce consistency, increase usability, reduce drift, and reduce maintenance. Single-sourcing works best when you have open-minded team members, a good content structure, source control, and a robust authoring tool such as MadCap Flare. To make the most of implementing single-sourcing of your content, your authoring tool or toolset must support single-sourcing to an effective level.

    Regards,
    Bonnie Kern

    Reply
  14. Pingback: Technical Writing News Nov 27th - Free Newsletter | I Heart Technical Writing

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>