By Christina Mayr | STC Associate Fellow
Understand the six major categories of tools commonly used in technical communication and how the tools you choose can define your career path.
“What tool should I learn?” is a daily question asked across Reddit, LinkedIn, and Slack by new and existing technical writers. If you are new to the technical writing field, you may believe from these questions and their answers that getting a job in technical communication relies upon knowing the authoring tool or markup language du jour, or that having the same skills as a software developer is a prerequisite.
There is no standard list of authoring tools new technical writers should learn, but early career technical writers should focus on creating a portfolio of writing samples using the tools they want to work with at a future job. Understanding popular tools, what they do, and why they exist will be imperative to a successful technical communication job search.
This article provides an overview of common authoring and publishing tools used by technical communicators, how to choose your tool learning path, how you can be more competitive in a tight job market, and what’s on the horizon for documentation creation and publishing.
What is a “Tool”?
Technical communicators use a variety of systems, applications, and extensions to get their work done. We use a variety of tools to brainstorm, mindmap, and outline (Word or Google Docs), and then switch to an entirely different tool for drafting content, either collaboratively or solo (Confluence, Flare).
Then there are systems for storing content and maintaining source file version control; tools for editing and collaborative review; and, of course, the publishing pipeline. The latter likely involves both automatic and manual processes across multiple systems that deliver packaged and formatted content to the end user.
In this article, “tool” refers to any application or program—open-source or enterprise, cloud, server, or desktop—that a technical communicator might use to author, manage, or publish content. Markup languages like HTML, XML, and Markdown are not “tools” exactly, but are often brought up in tools- and process-related discussions. Much like a software developer who can code in both Python and JSON, they might use one Integrated Development Environment, or IDE, to do their work. The IDE is the tool, not the language. I’ve grouped the major tools into six major categories (see Figure 1) and will discuss each one in turn:
Desktop Publishers
These tools package the main authoring and publishing processes into one program to make content creation and publishing for a lone writer or a very small team easy, simple, and inexpensive. Microsoft Word, Google Docs, Confluence, FrameMaker (unstructured), and GitHub Pages could all be classified this way.
As presented in my analysis of nationwide job postings at SIGDOC 2021, Microsoft Word is still one of the most frequently mentioned tools because it is readily accessible, used by most companies, and supports the main processes for delivering a small amount of documentation that doesn’t require advanced publishing like multiple outputs, multi-language translation, or creating different content for different audience segments or purposes (known as conditionalizing).
Help Authoring Tools
Help Authoring Tools (HATs) are HTML-first authoring tools for creating online help for a software product or Application Programming Interface (API). MadCap Flare is the major player in this space, with RoboHelp, Doc-to-Help, ClickHelp, and a few other programs competing for the remainder of the market share. These tools can support complex authoring processes and deliverables without an expensive conversion to an XML standard like DITA.
Generally, HATs contain the authoring and publishing piece but are missing the storage and delivery components. These tools may require a web server for HTML files or a direct transfer of the help files into a software product’s user interface. This is where Content Management Systems (CMSs) come into play.
Content Management Systems
There are simple CMSs that store content for consumption, with WordPress being the most well-known. Then there are also Component Content Management Systems (CCMSs) for componentized content (like XML files) that store content and make it easier to reuse and conditionalize content.
Powerhouses like RWS Tridion, Ixiasoft, and Vasont dominate this market, while Paligo and Heretto have garnered the attention of small-to-medium teams who want to do DITA without stacking tools together. Paligo offers an easy-to-use interface that purposefully obscures its DocBook underpinnings and provides source and version control, SME review, and HTML and PDF transformation.
Text Editors
Text editors can be simple or robust; oXygen is a powerful text editor useful for managing text files (such as XML) that are then transformed into HTML or PDF. If you’re working in a DITA environment, oXygen is the preferred tool of many product documentation teams, especially at large companies like Amazon Web Services (AWS). XMetaL and Arbortext are the main competitors to oXygen.
Visual Studio Code is a favorite of software developers, and if you are part of a team using the Docs-as-Code methodology, you want to be using the same or similar tools and workflows as the developers you work beside.
It’s important to remember that if you are on a team of writers, your text editor will be accompanied by non-local storage and version control systems like GitHub. If not using oXygen (which has built-in publishing capabilities), you will also need a way to transform the text files into their ultimate outputs.
Project Management Tools
As many technical writing teams do not have the luxury of dedicated project managers that understand documentation projects, often writers are saddled with planning, scoping, and tasking documentation and communication projects. Technical writers need to not only plan the documentation efforts but make what they’re working on visible to other teams.
Finally, while documentation members may not drive a project schedule, they may need to plan their work so it lines up with predetermined delivery dates. Many companies may use a methodology like Agile Scrum, popular in software development, so writers must align documentation deliverables with established sprints. Popular project management tools include Jira, Asana, Trello, Airtable, and Notion.
Everything Else
I didn’t touch on page layout tools (i.e., InDesign, Canva), presentation programs (i.e., PowerPoint, Keynote), graphic/video editing tools (i.e., SnagIt, Photoshop, Camtasia), or diagramming and whiteboarding applications (i.e., Miro, LucidChart). There are tools for other content and product development processes, including: UI design wireframing and prototyping (Figma, Balsamiq, Adobe XD); digital asset managers (DAMs); taxonomy and thesaurus managers (like PoolParty); and grammar, style, and tone checkers (Grammarly, Acrolinx).
The supplemental tools you’ll use will vary based on company culture and are easy enough to learn on the job. However, if you would like to add a particular skillset to your toolbelt, there are a multitude of free-to-use or free-to-try programs to enhance your portfolio samples.
Choose a Path, Choose your Tools
There are many ways to segment the work we do as technical communicators. One of those ways is by who we write for: developers and end users.
Developer-focused writers are commonly assisting with API and Software Development Kit (SDK) documentation, writing reference guides and procedures where the software’s code lives. This environment means that content teams are transforming Markdown, reStructuredText, or AsciiDoc files into static, serverless, HTML websites using something like Jekyll, Hugo, or Docusaurus.
Alternatively, documentation teams focusing on end user content may choose enterprise content creation tools, from FrameMaker, Paligo, or a multi-system DITA implementation, depending on their needs.
Of course, the world of technical communication is much more than software, and goes beyond developer or end user content. Many new technical communicators believe they must become an API writer to move ahead in their careers. Or they have to contribute to open source projects to get noticed by a hiring manager.
But this belief is severely limiting to the new graduate or career changer: technical writers are also needed for hardware and physical products; manufacturing and process engineering; utilities; healthcare; pharmaceuticals; and finance, just to name a few. The technical domain is going to play a role in the tools that would make you competitive for specific types of jobs. It’s important to follow major players in your desired domain or industry and make connections to keep up with changes happening there.
Staying Competitive in Today’s Job Market
The tools listed in the same categories above do the same thing, just in different ways, with their own strengths and drawbacks. For job seekers, choosing what to learn is going to vary based on your chosen path and what your local marketplace is asking for.
If you are interested in writing for developers, learning Markdown and building a simple portfolio in GitHub is a simple and easy way to start. You can then increase your knowledge and publish a more robust website using a static site generator, all while increasing your knowledge of the underlying language and improving your CSS skills.
For consumer product documentation, I recommend starting with Word and fully understanding and using the power of styles. This knowledge will serve you well as you move into FrameMaker or Flare, where you can single-source your content into HTML and PDF and contextualize for different audiences.
It’s not enough to simply list that you know specific tools on your resume. Demonstrating application of that knowledge through a portfolio sample using said tool will put you to the top of the “to interview” pile pretty quickly. In addition, understanding the business reason behind the tools companies use should be more valuable to a hiring manager than being an expert in any specific tool. In fact, many technical communication job postings don’t require a specific tool but simply request knowledge of it or a similar tool.
What you can take away from this is that being able to articulate why companies choose one implementation over another puts you in a better position to learn the company’s preferred tools and processes quicker. Understanding how the tool fits into the content creation process allows you to be better prepared to work within the strengths, constraints, and drawbacks of the tool, as opposed to just memorizing what buttons to click.
Lastly, building your virtual and in-person network with other writers, bloggers, and vendors will help keep you knowledgeable about the changes happening in the tools space. Attend conferences, join meetups, and stay active on LinkedIn and Slack. If you are new to technical writing, find a mentor that aligns with your chosen path to help you upskill, volunteer or contribute to projects, and expand your network.
The Future of Tools
You may have also heard these buzzwords: Content Engineering; Content-as-a-Service; Personalization; ChatGPT. What do all these things mean and why are they important?
In companies like Red Hat, various open-source tools and extensions are stacked together to create authoring, reviewing, and publishing workflows with scripts and other automation to ensure content gets to the user when they need it. In larger companies with consumer products, the people that administer, troubleshoot, and enhance the different tools being used may be called “Content Engineers,” or “Documentation Engineers” and are separate from the content-focused writers and editors. You may see these jobs as part of the group that manages the content lifecycle, often referred to as “ContentOps”.
Content-as-a-Service (CaaS) has also been making an appearance in tech comm circles lately. CaaS simply refers to the ability to create custom content that is chosen and packaged by the end user when they need it (instead of publishing a document whose structure and order is determined by the content team). In these companies, documentation becomes a product and potentially a revenue generator.
Along with CaaS, “personalization” has become a buzzword. Both users and writers want the ability to automatically (or with very little manual intervention) provide content based on a user’s location, audience profile (expertise or role), purchased product line, and other metadata. This is not done frequently nor very well at the moment, but companies like Fluid Topics are talking about what documentation teams need to do to make this a reality.
CaaS and personalization necessitates structured authoring and carefully researched metadata. This delivery mechanism is obviously an ideal for your end users, but certainly won’t happen through magic! Documentation teams need much more than static sites; componentized, structured content with dedicated information architects, user researchers, and transformation programmers (e.g., XSL-T or Prince) can work together to make personalized content a reality.
Companies who understand the value of personalized, on-demand content delivery may not understand the effort and expense to move all tools and workflows to a structured authoring operation. More and more, the desire to publish in a DITA-like environment without being an expert in all the underpinnings that make DITA work is valuable and attractive to teams being constrained by desktop publishing tools.
This is why cloud-based, all-in-one services like Paligo can sweep the market because of a company’s need to improve ContentOps but don’t have the resources to build a multi-person sub-team. These products allow small teams to do more complicated publishing without stacking tools together with multiple points of failure and frustration.
The future of technical documentation is at the same time more technical and less technical and changing constantly. While the ability to write coherently and create an attractive, easy-to-use document that solves a user’s problem will always be core skills of technical communicators, the newer tools on the market are making authoring and publishing processes more automated, so documentation will be less about writing and more about building content.
Generative AI and ChatGPT
I would be remiss not to include the implications of generative Artificial Intelligence (AI) like GPT3 and seemingly sophisticated AI tools on the rise. To close us out, here is a poem I asked ChatGPT to write about technical writing tools (edited for length and grammar):
I’m a technical writer, with skills on the rise. I use a variety of tools to organize and advise.
First on my list is Microsoft Word, A tried and true tool, it’s often preferred.
With tables and images, and formatting galore,I can create documents that are easy to explore.
MadCap Flare is another tool in my kit. It’s perfect for creating online help that’s easy to commit.
But when I want to use DITA,I turn to oXygen, it’s a fiesta.
With support for DITA maps, and DITA topic types too, I can create clear documentation that’s easy to review.
With structured authoring and automatic numbering too, I can create clear documentation that’s easy to peruse.
These are just a few of the tools that I use, To create clear and concise documentation that’s easy to muse.
So if you’re a technical writer too, Don’t be afraid to try out these tools; they’ll see you through.
While this poem won’t win any writing awards, the potential of GPT3 to help writers quicken and streamline the research, outlining, and drafting portions of creating documentation, remains uncertain. Technical communicators should watch this closely.
References and Further Reading
- Bailie, R., Nhem, A. “Case Study: ContentOps for Product Content,” Webinar from BrightTALK, brighttalk.com. May 11, 2022.
- “Developer Documentation Trends—Survey Results,” Tom Johnson. Last updated October 28, 2020, https://idratherbewriting.com/learnapidoc/docapis_trends.html
- “*How* you write influences *what* you write—interpreting trends through movements from PDF to web, DITA, wikis, CCMSs, and docs-as-code,” Tom Johnson. Last updated February 20, 2020,https://idratherbewriting.com/blog/how-you-write-influences-what-you-write/#trying-to-pin-down-noteworthy-trends
- Mayr, Christina. “Cleared for Departure: Preparing Students to be what Hiring Managers Need.” October 14, 2021. SIGDOC 2021 Raleigh Hub, 59 minutes. Video: https://vimeo.com/632152442; slides: http://shorturl.at/dtxJ3.
- O’Keefe, Sarah and Keith Schengili-Roberts, “Jobs in Techcomm,” The Content Strategy Experts podcast, November 7, 2022. https://www.scriptorium.com/2022/11/jobs-in-techcomm-podcast/
- Play with ChatGPT at: https://chat.openai.com/chat
- Swisher, V., Lacroix, F., Abel, S. “Breaking Free From One-Size-Fits-All Documentation,” Webinar from BrightTALK, brighttalk.com, October 4, 2022.
CHRISTINA MAYR is a technical writer, information architect, outspoken user advocate, and champion for the technical writing profession. Currently leading a small team of technical writers in an IT organization within the gaming industry, Christina prides herself on leading and coaching others to improve their skills in technical communication. Her professional interests include technical content strategy, content operations, and leadership.
After receiving her MA in Technical & Professional Communication from East Carolina University, Christina worked as a technical writer on technology-focused teams for various industries. In addition to her full-time job, Christina is also an instructor with the Duke University Technical Writing certificate program.
In her spare time, Christina runs a resume and career coaching consultancy, helping clients from all industries get better jobs and better pay by improving their job search strategies and application materials.
