What Tools Do Technical Writers Use

What Tools Do Technical Writers Use?Students and others trying to break into technical writing are always wondering what tools they should use. The latest tools survey from WritersUA seems helpful in answering this question.

The survey concludes that some of the most popular tools for technical writers are Adobe Acrobat, Camtasia Studio, Adobe Captivate, Dreamweaver, Madcap Flare, Framemaker, Photoshop, Robohelp, Snagit, and Visio.

Of these tools, Flare scores highest as a tool that participants can’t live without. They ranked it as a 5, meaning “very important.” Presumably this is because Flare does an excellent job in single sourcing to other formats, such as print and mobile. It’s an all-in-one solution, so it by definition it’s important or you’re not using the tool correctly.

The WritersUA survey is a little frustrating because these tools aren’t grouped by category. Some are screen capture tools, others are PDF conversion tools, others are image editing tools, others are video recording tools. I use Photoshop and Snagit, but ranking these along with Robohelp and Flare is to compare apples to oranges. Similarly, Camtasia Studio and Captivate are in another category. It would be helpful to sort the tools by category. (Still, it’s nice to see someone doing a tools survey in the first place.)

Of the help authoring tools, it’s interesting to see Flare rank so high. Flare is an excellent help authoring tool, and with a knowledge of CSS you can completely customize the webhelp and print output to look professional. However, its main failure is the lack of collaborative authoring. If you have 15 writers all contributing to the same help project, you have to import the content from other authors. They can use supporting tools such as Madcap Contribute, or Word templates. You can also try hosting Flare on SharePoint and enabling collaboration this way.

But I’m guessing that Flare is popular because most technical writers are solo sailors on their own ship, without the need for collaboration from other writers. In my career, the number of collaborative projects has been very small. I am usually the only writer for the project, which means collaborative authoring is unimportant. I don’t need a central repository installed on a server that numerous authors can access and pull content from. Content is also not reused between projects, since each documentation project covers a different product.

Sarah O’Keefe also has some comments on the WritersUA tools survey. See her post, The passion quotient. She notes that the survey highlights “the tool for which the importance is ranked the highest.” Despite this criteria in evaluation, I am not sure how I would design the tools survey differently.

Adobe RobohelpMadcap Flare

This entry was posted in beginner tips & careers, 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.

13 thoughts on “What Tools Do Technical Writers Use

  1. Sarah O'Keefe

    My post about the relative importance is not a criticism of the survey methodology. I am just fascinated by the results! The survey itself reports both raw totals (number of people who use Tool X) and then the breakdown by level of importance. I don’t think there’s any problem with that approach.

    1. Tom Johnson

      Sorry about my misinterpretation of your post. I thought you were pointing out the shortcomings of ranking by importance. I relaxed my paraphrasing a little. I’m not sure I totally understand what you were getting at with the passion quotient, if it wasn’t meant to highlight a potential shortcoming of the survey. Can you expand a bit? I know you were being playful.

  2. Mark Baker

    The thing that distresses me about this list is that it is dominated by things that are not writing tools at all, but publishing tools. That writers are still expected to do their own publishing strikes me as one of the tragedies of the profession, and a major part of why tech pubs does not get the respect it thinks it deserves in organizations. It is a big part of the reason that so many people still dismiss what tech pubs does as “making it pretty”.

    I have spent the morning going through a client infodump and pulling themes and ideas together by building a mind map. The mind map will never be published. It will be used as a research and planning tool. For me, it is a real writing tool, not a publishing tool.

    My favorite publishing tool is XSLT. My favorite writing tool may well be FreeMind.

    1. Melanie Blank

      Mark,

      Very interesting comments, and I agree! I would love to have my excellent writing, editing, organizational, (and interpersonal) skills considered more important than the no. of “making it pretty” tools I had experience with!!

      That said, I think that Flare helps a lot with the first three categories of skills I noted above. It could use some improvement in the “making it pretty” area when you have to output to PDF or Word (especially the latter). It’s very powerful, but it’s also very complex and takes a long time to learn to use effectively.

  3. Paul Pehrson

    I think these survey results are interesting, however, I think the information in the results is of limited usefulness.

    I would like to see a multi-page survey. On the first page, you’d present the users with a list of tools, and for each tool the respondent would say whether they (1) have used this tool in the past, (2) are currently using this tool, or (3) have never used this tool. You might also include a couple of different columns: (4) I’m interested in this tool and (5) I’ve never heard of this tool.

    On page 2 of the survey, you would just show the tools that the respondent has used before. This page would be a maxtrix-style questionnaire, and for each tool you would rank it in several categories. The categories would depend on the type of tool (Authoring only? Publishing only? Image manipulation? Data manipulation? Some kind of combination?).

    The results of this survey would not only show us how many people are using a tool, but they would likely show us some interesting information about what people like and dislike about the tool. The current survey tells me what tools people are using, but doesn’t give me any indication of how much they LIKE the tools they are using, yet that is the information that would be most helpful to me if I were considering switching tools.

    I mean, most of us probably use Word for some reason or another at work. But just because so many people are using it doesn’t necessarily say it is the best tool for the job.

  4. Maeve

    Thanks for your post Tom.

    I look forward to looking back on this survey a year or two from now when wikis catch up to the rest. Even if desktop applications move into the cloud, they will have to catch up with richly supported wikis like Confluence.

    I also look forward to the day a new tool emerges: one that combines the free-form formatting properties of InDesign with all the benefits of a wiki.

    Maeve

  5. Leigh White

    A useful survey, to be sure. At the end of the day, we do have to use tools, and it’s helpful to know what those are. That’s a concrete thing that students and active writers can add to their skill sets.

    I agree with Mark Baker in that it’s a shame writers are still expected to do their own publishing. It’s been my experience that publishing eats up a disproportionate amount of time, much of it in repetitive tasks that could and should be automated. My favorite authoring tools are Notepad++ and . My favorite publishing tool is the DITA Open Tookit.

    What this survey misses, and what–granted–would be harder to quantify, is what skills are important. Almost any tool will be adequate if the information is well architected and well written. Learning to use Flare (for example) is easier than learning to interact with developers, read and interpret a functional specification, write in an Agile environment, elicit helpful feedback from SMEs, gauge users’ needs, and so forth. And that’s just the problem–so much focus is on tools at the expense of the more important skills, with the “perfect” tool often being expected to make up for the lack of the other skills. Or worse, the documentation being tailored to fit into what the tools can deliver rather than what the users need.

    So…not to dismiss the importance of well-designed tools, but I’d really like to see tool discussions take a back seat to skill discussions, especially when we’re talking about students and new writers.

  6. Joe Welinske

    Thanks for highlighting our survey in your blog Tom. I’d like to address a few of the comments.
    We’ve been doing a tools survey since 2000. “Tools” used to be wrapped in with our “Skills and Technologies” up until 2009. You can still see all of them: http://www.writersua.com/surveys.htm
    Over the years, we have found that some things worked with the survey and other didn’t. One of the key aspects of a survey like this (at least from our POV) is that if it gets too long and complicated you run the risk of significantly reducing participation. It also reduces the statistical significance of individual responses. The current version is simple and quick and valid.
    From a respondents perspective, having an alphabetized list is an easy way to participate in the survey. For the summary report, I agree, it could be better to have categories. However, it gets complicated and creates biases. One might easily put RoboHelp in a certain, single category, but tools like Author-it and ePublisher cross into different areas. If there was a standard list of tool categories for our profession, I would certainly use that.
    For now, I feel it is better to just supply the aggregate data and let everyone make their own lists. Anyone can copy the data into a spreadsheet and slice and dice it based on their own interpretations.
    For example, Tom mentioned that Flare was “ranked high”. The survey doesn’t actually say that. Tom probably looked at the “5″s and made an assessment. But what about a tool that has a lot of “5″s but also a lot of “1″s? You might have to make a different judgement.
    I’m not sure I completely understand Mark’s point about writing tools. Personally, I find that I “write” help much better when I am immersed in a tool like RoboHelp or Flare. Also, in this survey I have tried to distinguish between tools and technologies. A “tool” like xMetal builds upon “technologies” like XSLT. Technologies are listed in our Skills and Technologies survey which is currently in progress.
    Finally, if you look at the footnotes and comments below the table you can get a sense of the diversity of choice and opinion there is, even for this small set of tools.
    All of the comments definitely get filed into my idea bank for future surveys.
    Thanks,
    Joe

    1. Mark Baker

      Hi Joe,

      My point about writing tools is this: There is a difference between writing something helpful, and building a help system. The former is a technical communication task; the latter is a publishing task.

      To be sure, the desktop publishing model has been with us for so long, both in the creation of manuals and in the creation of help, that it is easy to assume that the two tasks, writing and publishing, are part and parcel of the same thing. Many people today can’t imagine doing the writing task in a way that is divorced from the publishing task. They have simply never known it any other way.

      Some of us, on the other hand, have always hated the mashup of writing and publishing. The irony for me is that I have spent much of my career in the publishing technology business, so I write about publishing and publishing systems a lot. I also design and build writing and publishing systems. But I still hate the mashup, which I why I design and build and write about systems that separate writing and writing concerns from publishing concerns, even when I am writing about publishing.

      1. Joe Welinske

        I see what you are saying Mark. I think we are of the same mind. There are a lot of possible UA options to every challenge. Once I have decided on the types of deliverables, then I use the appropriate tool to create the information and digital deliverable. For my work with mobile, there haven’t been good tools to work with. So it has been sketching on a tablet for the design, writing and coding in Notepad.

  7. Andrew

    I would like to comment about the lack of collaboration in Flare. Have you ever tried to use a version control system? Something like that will AUTOMATICALLY make it a collaborative system. It is true, that a collaboration system would allow for things like comments and tagging. However, for having multiple people working on a writing project and contributing in a variety of ways, I would STRONGLY recommend using a simple tool like Git or Mercurial (Hg).

    For no cost, you can create an account at http://www.bitbucket.org. Create a repository and clone it to a directory on your local computer or laptop. Add your project files from Flare. From a command line it is as simple as

    c:flare_directory : hg addremove
    c:flare_directory : hg commit
    c:flare_directory : hg push

    Now you have added your files, committed the changes to your local repository, and pushed the changes back to bitbucket for others to access.

    Each morning, (or whenever someone alerts you to a change you have been waiting for) open the terminal and type:

    c:flare_directory : hg pull
    c:flare_directory : hg merge

    Now you have a working copy of any and all changes that were made by anyone on your team. This process is extremely effective for highly collaborative open source coding environments like Linux and MySQL. This is part of our regular workflow as software developers and content creators.

    There are also excellent GUI tools like TortoiseHg and GitGUI. Then you do not need a command line process. Just look directly at the history and select a revision (branch) that you want to work with. Easy rollback, easy shelving, easy sharing. Easy everything!

    1. Mark Baker

      I agree entirely, Andrew. Alas, too many in tech comm have an ingrained prejudice in favor of portmanteau tools that do everything in the same GUI, rather than using a collection of simple, reliable, and inexpensive tools that would let them design a work environment to suit their business processes. It is as if a carpenter were to reject their entire tool belt and insist on doing every part of their job with a Swiss Army Knife.

      I would advise every tech writer, before they set out on their next tool shopping trip, to sit down with their friendly neighborhood software developer and ask them to describe the collection of tools that they use to get their jobs done, and how their work flows through those tools.

Comments are closed.