Reader Question: "My Wish List for Technical Writing Tools"

by Tom Johnson on Dec 31, 2012
categories: technical-writing

I recently received a comment from a reader who sent me a wish list for technical writing tools. Sam from Canada writes,

Hi Tom,

I've been enjoying your posts along with Mark Baker's. You both have good points about technical writing trends. I could be totally wrong, but maybe it's not the tech writers that are resisting change. Maybe it's the companies making the tools/money that are resisting change.

I can't believe I'm the only writer out there frustrated with the lack of good documentation tools. Adobe tools are especially frustrating, and they're the ones most companies typically turn to because they're "industry standard" and relatively affordable. RoboHelp hasn't changed a lot since it was first released, so the help I produce with it still looks like it's from the '90s. MadCap appears to be similar. Many companies I've worked for can't afford to develop a custom tool for their help and most can't afford to invest in monster content management systems that promise single-sourcing. DITA and Documentum aren't solutions, and "re-use" is grossly overrated. The companies I've worked for can't use server-based help for security and firewall reasons and can't put their documentation out on the Web for the same reasons. (I just can't imagine requiring a user to enter a user name and password to access the documentation for a product.) So we're stuck with PDF and application help from the '90s.

I've watched companies invest in monster software solutions for their documentation only to discover the tool didn't resolve their problems after all. But they were too heavily invested in time, money, and resources to abandon it for something better. That's what the companies count on, I suspect. The constant trend in technical writing seems to be for someone to preach about a new solution, write and sell books about the solution, and then sell their monster software solution to companies willing to invest all their time, money, and resources in it.....even though it doesn't solve their documentation problems.

What I'd like to have:

• My hardware manuals to look like this: http://www.dozuki.com. But there's that security thing again.
• True single-sourcing that doesn't require FrameMaker and RoboHelp, an unmanageable database, or an unaffordable monster tool.
• A tool that allows manageable comments from and interaction between readers (Wikis are too labor-intensive).
• A tool smart enough to write context-sensitive help in the software developer's environment but does not require the writer to have a programming degree (Microsoft's XAML files come close). Users want and need this type of help.
• For software, a built-in screen-recording tool as easy as Camtasia. Users want to watch short videos instead of reading a sea of text. VersionOne training videos are wonderful!
• A tool that can do Google-like searches. That's what users want.
• A tool that will grow with changing industry requirements.

All that won't happen in my career life time, but it's a nice wish list. Thanks for listening.

First of all, I think this is a great wish list. Sam expresses many of the frustrations and pain points of technical writing tools. I'll share my thoughts here and then invite readers to respond with additional comments below.

Content Versus Tools

You mentioned a few things that caught my attention:

I've watched companies invest in monster software solutions for their documentation only to discover the tool didn't resolve their problems after all.

A tool that can do Google-like searches. That's what users want.

A tool that allows manageable comments from and interaction between readers (Wikis are too labor-intensive).

These three frustrations point more to content problems rather than to tool problems, don't they?

With the first point, companies tend to blame the tool rather than the content. What problem are they trying to solve with an expensive tool solution? Is the solution derived from specific user complaints about the tool? I tend to wonder if the requests for better tools aren't attempts to fix a content problem that isn't necessarily related to the tool.

When you say you want a tool that does Google-like searches, aren't users really saying they want to find answers like they do on Google? Google itself has a simple interface. But Google has an exceptional amount of content, especially long-tail content that provides answers to niche questions, edge cases, unusual scenarios, every troubleshooting issue you can fathom, and more.

All too often, help manuals stick with obvious instructions, novice-oriented scenarios, and mainstream tasks. Many tools have a Google-like search and interface (for example, Flare and Author-it provide this), but again, Google's strength is in surfacing relevant content. If help systems incorporate Google search but can't surface the relevant content, it doesn't solve the problem.

Finally, with your request for a tool that allows manageable comments and interaction, this again points to content. Responding to user comments can be a huge time commitment, more than most writers can keep up with. In my organization, we have a busy user forum that generates a lot of comments from users. We have other feedback channels too. The emails and forum threads roll in non-stop on every imaginable topic. If I were to keep up with it all, I wouldn't be able to write any new documentation. Again, it's a content problem more than a tool problem.

Some users do help other users, but if you put the interaction model inside the online help, it puts the burden on the technical writer to interact. Do you have bandwidth to spend 30+% of your time playing a support role? It might be something to consider before you wish for comments and other interactivity with help topics.

Overall, I think that we blame our tools much more than the content. Most of the time, help is poor because the content doesn't address all the users' questions, needs, and scenarios. If we channeled our tool energy toward content instead of tools, we would probably have a lot fewer problems with tools.

Content Re-use and Single Sourcing

You mentioned two other points about re-use and single sourcing:

•  "re-use" is grossly overrated
• True single-sourcing that doesn't require FrameMaker and RoboHelp, an unmanageable database, or an unaffordable monster tool.

What exactly is the difference between re-use and single sourcing? Here's how I understand the two terms. Re-use mainly refers to using the same content either within the same project or across multiple projects. Single sourcing refers to publishing the same content in multiple formats, such as in print, webhelp, and mobile.

I agree that re-use is overrated, but it may be due to my organization's products. I don't support multiple varieties of the same software product (e.g., lite, standard, and pro models), nor do I support multiple versions of the same product (e.g., version 6, version 7, version 8). And most of my products don't have overlapping content. As a result, I rarely reuse content.

I do single source with print and webhelp. However, here I think most tech comm tools greatly err. Rather than publishing a separate output for print, webhelp, and mobile, it would be better to provide one output that adapts to these three formats. (Well, at least to the latter two formats.)

Here's why. We can no longer be sure whether users will access our content on a laptop, tablet, or mobile device. Granted, if you're documenting software that can only be accessed on the desktop environment, device pluralism may not be a huge concern. But as more and more software becomes browser-based, and as more people search on Google for help related to your product, and those searches or browsers are on tablets or smartphones, the help needs to adapt to these devices.

Current trends in responsive design are to create a website with media queries that adjust the style based on device and browser. For example, the stylesheet might have properties such as

@media only screen and (max-width: 480px) {
.top-navigation:display:none;
}

This means that for smartphone devices, with a maximum width of 480 pixels, the display will hide the top navigation element.

You can also include print-specific styles by adding properties such as the following to your stylesheet:

@media print { body { width: 100%; } }

This tells browsers that when printing the content, apply a body width of 100%.

By defining styles for different mediums in the same stylesheet, we can single source the formatting without duplicating the content into different outputs. One output adapts to all the different devices.

Since these media queries and stylesheet properties conform with current web standards, we don't need special web tools to make this happen. We just need to use tools that conform to these web standards. We also need to increase our expertise with media queries and print styling.

Of course, if your output has different content entirely, such as a beginner's guide versus an administrator's guide, that content difference can't be solved with media queries. Still, my wish list for tech comm vendors would be to provide responsive webhelp layouts.

Tech Comm Tools Versus Web-based Tools

I'd like to respond to a couple of other points:

My hardware manuals to look like this: http://www.dozuki.com. But there's that security thing again.

RoboHelp hasn't changed a lot since it was first released, so the help I produce with it still looks like it's from the '90s. MadCap appears to be similar.

As you mentioned, web-based solutions don't work when your content is confidential and the software is installed locally on a computer. I don't have a solution for that, other than to say I think browser-based software is becoming more of a trend rather than software that you download and install. And if the software is browser-based but restricted, you could at least put the help on the same server as the software and thus inherit the access permissions.

With regards to the eternal Robohelp and Flare battle, I see this competition as a catalyst for continued improvement with both tools. The two arch-rivals are always trying to undercut each other. I think each would see its product as superior. But rather than being sucked into this debate, I'll instead weigh in on a different angle: tech comm tools versus web tools.

Do tech comm tools keep pace with the evolution of the web? Browser-based tools like the Dozuki tool you mentioned take advantage of more web-based enhancements and capabilities. We're growing more and more accustomed to editing directly in the browser, so similar web-based solutions such as WordPress, Mediawiki, or other online CMS tools feel so comfortable.

However, there's a fundamental rift between web-based tools (which allow you to edit and publish within the browser) and tech comm tools (which usually do the editing and publishing offline). Web-based tool creators don't see the need for some of the features of tech comm tools — namely, building books to publish in PDF format, re-using content between topics and projects, context-sensitive help, exporting the content into XML format for translation memory systems, delivering offline help, and more.

This gap between tech comm tools and browser-based tools is closing, as more tech comm companies are moving to cloud-based solutions (for example, Author-it recently rolled out a cloud solution).

However, I think users are growing accustomed to limitations of browser-based tools and are no longer looking for all the features provided by tech comm tools. Most prevalent, in my opinion, would be the declining interest in the long PDF manual.

In 2013 and beyond, I think we'll see trends away from long online PDFs toward more browser-based online help solutions (especially with multimedia). Agile methodologies will continue to increase, and as such, software instruction will need to be updated constantly. Users who want to ensure content is up to date will look for web pages rather than PDF content.

Fewer and fewer users are ever offline now, as they can carry smartphones and tablets wherever they go, taking the Internet with them in their pocket, ensuring that they're just a search screen away from accessing the knowledge they need. With this always-online-and-always-available model, who needs a PDF manual?

Video Tools

Finally, I'll respond briefly to your comment,

"For software, a built-in screen-recording tool as easy as Camtasia."

I don't see the need to integrate a video editing tool into a help authoring tool. It would create too much complexity within the interface. I'm perfectly happy creating videos on a Mac using Camtasia and then embedding them into help topics. No tool can automatically create a video from a set of written instructions that is in any way worth watching. Videos take a lot of time to create and edit, no matter what.

What I would like to see, however, is better integration of MP4 videos into tech comm tools. I'd like jQuery effects to make videos pop-up and dim the background, to rotate through other videos, and more. With HTML5, we have more possibilities for integrating video into web pages and for allowing users to interact with the videos. Again, though, the innovation is with the web rather than with tech comm tools.

Trends for 2013

I know I didn't respond to all of your points, but hopefully readers can fill in where I left off.

As I was finishing this post, I received an email from WritersUA announcing the opening of their 2013 user assistance authoring tools survey: http://welinske.com/tools-survey/.

I like browsing the results of this survey, but it's a bit limited. It tells us what tools technical writers are currently using, not what tools technical writers want to be using. Your wish list highlights the need to know what tools technical writers want to use. For that alone, I think this wish list is a valuable addition to the ongoing tools discussion.