A tool may only be as good as the person using it, but that does not mean we have to resort to using sub-par tools. Regardless of your profession, you will need some tools to get the job done.
Whenever I start working with anything new, my favorite part and one of the most exciting things is testing all available tools. Usually, there is a plethora of tools to choose from, and this is no different in technical writing. In this post I will not cover some tools, like Swagger/OpenAPI or Docusaurus, and I will try to keep this very high level and go into more detail in future posts.
What do you need for technical writing?
Let's start with the obvious ones, although I will not spend too much time on those. In the digital age, you probably won't use a pen and paper to jot down your documentation. Because of this, you will need a computer and an internet connection. Now that we have that out of the way, I'll introduce the technical writing tools:
- Authoring tool (required)
- Publishing tool (required for online documentation)
- Component Content Management System (CCMS) (highly recommended)
- Version control tool (highly recommended)
- Spell-checker tool (highly recommended)
- Illustration tool (if required)
Nowadays, most of these are integrated into one tool, either as a package deal or as integratable plugins.
Authoring tool
Authoring tools have many types. There are What You See Is What You Get (WYSIWYG) ones, some of which you are probably familiar with, like Microsoft Word or Google Docs. These can be great for minuscule products where speed is paramount, and you don't really have to worry about platform dependency and scalability. A good use case would be if you (or your client) are looking to sell one single physical product like a high-tech pencil sharpener. In this case, you probably won't require online documentation, so you could simply write your documentation in Microsoft Word, print it, and ship it with the product.
If your product is a bit more complicated, or you plan to publish it online, you will probably have to use some type of structured authoring tool. A structured authoring tool is a text editor where you write using a markup language like XML. The main difference between structured authoring and regular text editors like Microsoft Word is that in structured authoring, you use a standardized encoding system to control the text's structure and formatting. To put it another way, in a structured authoring tool, you are not only communicating with people but with machines as well, explaining to the computers how you would like certain parts of the document to function. For example, this blog post was written using Markdown, which is a form of markup language.
 |
|---|
| A comparison between Markdown and Google Docs WYSIWYG authoring tool |
Some structured authoring tool examples:
- Adobe FrameMaker
- oXygen XML
- Arbortext
I will create a post comparing these tools sometime in the future.
Publishing Tool
So you have created your amazing documentation, but now you are thinking... "how will I show this masterpiece to the world?" This is where publishing tools come in.
Most publishing tools are sold bundled together with the authoring tools as a package, correctly assuming that if someone wants to write something, they will eventually want to show it to the world as well. The simplest of publishing tools basically put out your content to the World Wide Web according to a predefined stylesheet. More complicated ones tailor the reader's experience according to their needs, for example, showing more information to first-time users and less to veteran users.
Some publishing tool examples:
- oXygen Publishing Engine
- MadCap Flare Publishing
Component Content Management System (CCMS)
Component Content Management Systems help you manage content on a more granular level (component level) instead of on a document level. This means that instead of building up each and every document from zero, you could instead build each document up from building blocks (components).
 |
|---|
| Comparing component-based authoring to document-based authoring |
You could ask yourself: “Ye, sure, but why would I want that?” and that would be a fair question. So what do we gain? Granularity and scalability! Imagine this situation: Let's say you have documentation for four different mobile phones. All these phones have different hardware and some functionalities unique to a type of phone, but they all share the same operating system. Now, let's say that after a year or so, the company decided to change the operating system of said phones. You would have to open up all four documents and change the operating system's name. This isn't too painful when the company only sells four types of phones, but let's imagine that the company has 100 or even 1000 phones?! Suddenly you have to dedicate a whole week just to change a single line in 1000 documents.
This situation is entirely different if we are using a CCMS. You would have a single component (an information chunk) containing the operating system's text. You would open this information chunk in your CCMS and change the name of the operating system. With this simple action, you've just changed it in 1000 documents (or however many you'd have used this). Now we are talking about scalable!
Some CCMS tool examples:
- IXIASOFT CCMS
- Paligo
- Storyblok
Version control tool
Versioning or version control tools are used to keep track of the changes in documentation (or in SW) over time. This can be used to compare different versions and to revert back to older versions if needed. Most versioning tools nowadays are git-based, but some all-in-one tools have their own versioning tools built in. Versioning tools can be used to create branches of documentation.
 |
|---|
| Many functionalities can be bundled into a Technical writing SW |
To give you an example: Let's say you have three technical writers working on a cutting-edge cybersecurity software that supports IPv4. The software has one document called Cybersecurity Management. A developer team starts working on an IPv6-based extension, which will require some changes in the documentation. Meanwhile, the updates continue for IPv4. So the technical writer team decides to branch this document into two branches: one for the regular IPv4 stuff and one for the new IPv6 updates. Two technical writers will continue working on the IPv4 functionality, and one technical writer can start working on the new IPv6 updates without disrupting the IPv4 content. When the IPv6 updates are released for the SW, the technical writer team can merge the two branches into one. After a week, it turns out the SW updates are quite buggy, and they decide to remove it and put the IPv6 release on hold indefinitely. The technical writer team can revert back to the IPv4 version of the document with the click of a button.
You can probably see the similarities between the use of a CCMS tool and a versioning tool in this hypothetical example. Its main use comes into play for bigger projects where cooperation on a product is key.
Spell-checker tool
This one is pretty simple. Since it is unavoidable to make a couple of mistakes when writing documentation, a spell-checker tool always comes in handy. There are authoring tools where a spell-checker tool is already included and 3rd party ones, which can either be integrated into the tool you are using or used separately. These tools can range from extremely simplistic ones, only flagging typos or unknown words, to more complex ones where you can even check your document from a stylistic perspective or enforce a corporate style.
 |
|---|
| An example of a spell-checker tool: Grammarly |
You are probably already familiar with at least one of these examples:
- Grammarly
- Acrolinx
- Microsoft Word
Illustration tool
Illustrations can be the heart and soul of documentation. A great illustration can explain a complex concept easily, while the same might be extremely difficult to convey over text. On the other hand, a bad or unnecessary illustration may completely derail an audience from the content you would like to highlight.
 |
|---|
| Case in point — this is an unnecessary albeit cute illustration |
There are many illustration tools out on the market:
- Adobe Illustrator
- GIMP
- Inkscape