Reader Question: “My Wish List for Technical Writing Tools”

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

Madcap FlareAdobe Robohelp

This entry was posted in general on by .

By Tom Johnson

I'm a technical writer working for The 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS or by email. To learn more about me, see my About page. You can also contact me if you have questions.

11 thoughts on “Reader Question: “My Wish List for Technical Writing Tools”

  1. straygoat

    Another interesting article. I have always hated PDFs and am glad that more people are now seeing that HTML/XML web pages are the future. As someone who works in technical documentation and also web copywriting, I welcome the day where the two disciplines meet.

    What I would like to see from Flare is the ability to output Google-friendly pages (so no MadCap-specific code elements and better use of meta tags). That would allow us to use Flare to create online help, mobile help, PDFs (yuk!), or genuinely optimised web content from a single source.

  2. Riley VanDyke

    Although it’s happening a bit too slowly, I see a gradual shift from a Ptolemaic universe where *authoring* of content is at the center of things to a Copernican universe where *management* of content is at the center.

    My Wish List thus begins with the ability to choose from multiple competing tools that best support my management and generation of my standards-based body of content, a.k.a. my “Content Sun”.

    Standards-based in this context meaning that there is no proprietary detritus in my content. So if for any reason I become dissatisfied with Vendor A or Tool B, I can readily discard it and start working with Vendor C or Tool D with a minimum of effort.

    Stated another way, if my content is truly standards-based, then I am no longer obliged to spend too much time worrying about which brand of tool I’m “locking myself into”. I instead can find the vendors and tools that provide the greatest value at any point in time, confident in the knowledge that my content isn’t “branded” in some way that prevents me from readily using any and all other standards-compliant tools and vendors as I see fit.

  3. Dimitri Tetsch

    Vendor post
    __________

    HelpServer is a web-based & server-based cms to publish help & documentation. Publishing however does not mean creating files. In the HelpServer universe publishing means making content available in real time over the internet for your end-customers.
    Publishing is in fact like turning a switch in the database, that says now this content can be accessed in realtime by customers. It also means that you change a topic and selectively publish only the topic that has changed.

    You can either make all of your content publicly available via the web and even allow Google to index your public content or you can only have content available to your customers. For the latter you could have users logon using username + password, or you could make use of single sign on possibilitities that come with HelpServer like logon exit procedure or activation exit procedure.

    If your application is a web based app that runs in a browser, you could for instance use an activation exit procedure to check if the user has an ongoing session in your app and if yes grant access to the help.

    Also with HelpServer end-users can rate content and provide feedback, authors can be notified when feedback is provided.

    What is also a nice feature is that end-users can print entire nodes to PDF in real time. When an end-user launches a print request the PDF will be created on the server side by HelpServer. This is quite fast and the advantage is that the PDF always reflects the currently published version.

    Next to offering documentation via a front-end web portal you will be able to reuse your documentation as help by making use of aliases and pointers.

    Further on HelpServer improves single sourcing since all content is stored as XML in a database that resides on a server. In order to improve reuse the following techniques can be used: reuse content objects like topics, work with snippets and/or embed topics in topics, reuse images and videos from a project gallery.

    HelpServer also allows what we call Smartcontent: by making use of variable name/value pairs and smartrules (=conditions) that evaluate if a variable has a certain value. If the condition evaluates to true, content will be shown. This will help your improve your authors reuse possibilities.

    HelpServer authors can work in a workbench that is installed on their computer, or can invoke the workbench in a browser as a RIA (Rich Internet Application) where not every topic needs to be saved before the author can jump to and work on another topic.

    HelpServer can be purchased and installed on your own server (700 Euro per concurrent author) or can be rented as SaaS starting from 35 Euro per month per concurrent author.

    For more information visit http://www.helpserver.eu ask or contact marketing@helpserver.eu for a 101 web meeting. Free trials are available from the HelpServer website.

  4. Oana

    Sam has a great wish list; one every tech writer should wish for… I’ve been thinking lately about the best tool for technical writing. We do have the employer’s constrain who will not invest their money in better tools for documentation. They say it’s a waste, they do not see the big picture.
    Excellent article to end 2012, Tom! May the 2013 you delight us with more technical writing trends and innovations!

  5. Pingback: We Need a New Economic Model for Tech Writing Tools - Every Page is Page One

  6. Peter Grainge

    I find it very hard to see how Sam can state that neither RoboHelp or Flare have changed a lot since their release. RoboHelp is now 21 years old and there have been many changes. I don’t use Flare but I do know they have made many changes since the product was launched.

    In RoboHelp 10 there is an HTML5 output enabling one set of source documents to be output with very different appearance to suit the many devices out there now. I believe Flare has something similar. I am not going into the relative merits as the issue here is change, both have changed but I only know what is in RoboHelp. A quick look at the RoboHelp Tour at http://www.grainge.org/pages/authoring/rh_tour/index.htm will show what has changed in RoboHelp over the last four releases.

    Sam, when you say your help looks like it is from the 90′s, is that just because of the tripane format or the general appearance? I have seen some very modern looking help still using the tripane format. I also saw something created using Flare that looked more like what you want but probing suggested it required a massive effort. That is not a pop at Flare. Simply that if you are using a help authoring tool to create something like the example you point to, it is going to require a lot of effort as essentially it is the wrong tool. It’s rather like picking up a set of metric size spanners (wrenches) and complaining they don’t fit your imperial size nuts and bolts, they were not designed to. You have to use the right tool for the job. Something like Dreamweaver would generate what you want but no TOC or Index to make the user’s life easier.

    SECURITY

    That’s an issue whatever you use and really one for the developers to resolve.

    SINGLE SOURCING

    Why rule out RoboHelp? I use one project to produce the OLH for a product that goes to five different markets and works in a very different way for each.

    COMMENTS

    There are a number of web sites offering the ability to integrate commenting into your help but I suspect security and confidentiality between clients would be an issue.

    RoboHelp offers two versions of AIR Help and the locally installed version has commenting. Whether or not that would suit is another matter.

    CONTEXT SENSITIVE HELP

    Any topic can be context sensitive. It is down to you to structure your help to provide topics to support a screen and then liaise with your developers so that it can be called. That could be using Map IDs or simple URLs. The writer does not need a programming degree or indeed any ability to program.

    BUILT IN SCREEN RECORDING

    Not everyone does need that so I see that as a separate tool so that you can buy what you want and can afford. Both RoboHelp and Flare allow you to integrate such recordings.

    GOOGLE LIKE SEARCHES

    They are in RoboHelp’s HTML5 outputs. One of the changes. I don’t know what Flare offers.

    A TOOL THAT GROWS

    You just have to upgrade as requirements change. That’s the way it is with any software and many other things. The Model T was great in its day but it would be a bit scary now on an interstate.

    ****************************************

    It seems to me your first decision is whether you want the web site approach that may look more sexy or something that can still look very nice but is much more functional for the purposes of providing help. Once that decision is made, the type of tool is dictated and then it is a case of organising content and making it look good.

  7. Keith Soltys

    Wow, you sure ended the year with a bang. What a great post. I’ll be putting up a short response to it on my blog on Monday, but I thought I’d comment here as well.

    With regards to the section on tech comm tools vs. web-based tools, this is something I’ve been grappling with at work. We’ve eliminated PDF manuals for most of our operational documentation, but most of our technical specifications (information about protocols and data feeds that our customers use to connect to the exchange) are still published as PDF documents. I’d like to change that, but it’s not something I can do on my own, as I have to consult with the stakeholders – the development and business groups that own the content and who deal directly with our customers. Sometimes the technical issues around content reuse and publishing are the easiest to resolve – organizational and cultural changes are much harder to implement. This is something that you didn’t really touch on in your post, and I’d like to see your thoughts on the subject.

    1. Tom Johnson

      “organizational and cultural changes are much harder to implement. This is something that you didn’t really touch on in your post, and I’d like to see your thoughts on the subject.”

      I completely agree. I do not have good advice on this subject, but it would make for a great post. I will see if I can squeeze and idea out of that. Thanks for the tip.

  8. Pingback: Four Less Common Types of Technical Writers Companies Are Looking For » eHow TO...

Comments are closed.