How to choose a tool for software documentation?

The company grows in size. People come and go. But the organization should keep operating even when the most knowledgeable people leave. Preserving knowledge in the form of documentation is one way to do it. There is a lot of software out there that helps organize knowledge and documents. But how do you choose a tool for software documentation? Which software documentation tool is the best? There are multiple aspects that you may consider. I’m going to cover them in this article. It may feel overwhelming at first, that you have to think about so many things to choose the right tool. But it can also serve as a reference list or a guideline that can bring up one important question that you simply forgot to ask. 

What types of documentation do you need to cover?

There are multiple types of documentation, and different kinds may require different tools. Internal docs can benefit from easy editing, while customer-facing docs should have more strict requirements. High-level overview docs or design documents may be described in one place, containing multiple images. API reference could be stored together with source code and follow the same format for each service. Additionally there are dedicated tools specifically for API docs.

Who’s going to edit it?

Is everyone allowed to edit every page or only certain people? Does the tool support such permissions? 

Are the docs going to be edited only by tech people or non-tech as well? For instance, not everyone may feel comfortable with Markdown syntax, or working with version control systems. 

Do you need granular access to specific pages?

Can everyone with access to the tool, access every page? Or do you need to restrict some pages to only certain departments?

Do you need the option to make single pages public outside an organization?

Do you need to store images or videos?

Are any of the formats you need unsupported by the tool? Are there limits when it comes to the size of a single image or a video? 

How well funded/established is the company behind the tool?

Smaller companies look for competitive advantage. That may result in a tool that is cheaper, better serves a single use case, or is generally easier to use.

On the other hand, big enterprises have less risk of disappearing in 5 or 10 years, have better integrations, or support way more use cases.

How easy is the data export?

The product of your choice might have gone away because of the company going bankrupt. Or you might have received a way better deal on a different product. How easy is it to migrate all the data from one system to another? Does it export to common formats like Markdown, XML, or JSON? Or does the new company offer a migration service? It’s worth being aware of tools that are easy to get into and hard to escape. 

Do you have a workflow for editing docs?

Do you do reviews of the docs? Does the tool support comments or other means of collaboration like for example suggestions? 

Do you need to preserve the history of changes? How long? Keeping docs in e.g. GitHub gives this out of the box, but at the cost of learning how to use Git. 

Does it have a good search?

People look for information in different ways: traversing the document structure, looking at the document titles, or searching for a specific term. It’s good when the search is well-balanced providing not too much information but also not too little. It’s nice when it supports fuzzy search and can recognize synonyms. 

How are you going to organize documents?

Does the tool support additional dimensions of organizing docs? For example labels or custom fields. Do you need to be able to create dynamic pages based on queries? 

For example in Notion you can create a “database” where sub-pages can have custom fields and you can organize documents based on these. Or in confluence you can create dynamic pages that query all the pages with specific labels. 

What kind of components do you need?

• Do you need tables? Do they need to be interactive and support ordering and filtering? 
• Do you need collapsible components? 
• Do you need code syntax highlighting? 
• Do you need to embed PDFs? 
• Does it support generating a table of contents based on headers?

Do you need an overview of other pages when reading the document?

For instance, if you keep your documentation in Google Docs it’s more difficult to navigate to other pages, you don’t have a sidebar with documents structure. 

Do you already use other software that comes with a documentation tool in a bundle?

That’s usually a fairly good reason to choose certain tools. Nowadays software companies use multiple SaaS products. 

Examples could be:

• using Jira for project management can easily integrate with Confluence
• using GSuite brings Google docs with it
• using GitHub for the version control system can host Markdown files in the repository. It also has its own Wiki feature. 
• using Microsoft products brings Office365

One company may use multiple products so they still need to decide which documentation tool to choose. Sometimes they may choose none of the existing ones, and bring one more SaaS product, specifically for the knowledge base.

Is the tool extensible?

Does the tool let you create custom plugins? Or does it have a marketplace of already existing plugins? Example: Add-ons and App Script for Google Docs. 

Does it support integrations? For example:

• project management tools e.g. embedding user story tickets into documents?
• spell checkers e.g. Grammarly
• Slack notifications when updates are made or your mention is added to the document

One interesting use case of extensibility is keeping diagrams as code. That makes editing them easy. GitHub for example supports Mermaid diagrams in Markdown.

Is it nice to use?

It’s hard to ignore that aspect. If the tool is slow or has a bad UX, that can discourage people from editing the pages and as a result, hurt overall knowledge sharing in the organization.

Many tools take ideas from each other creating a more or less unified experience between them. Some ideas make document editing easier and faster. That include:

• slash + a command or a component
• using hash (#) to quickly create headers
• converting dashes into bulleted lists

Does it have limits when it comes to the number of pages/images/gigabytes stored?

That rarely should happen considering that companies want to keep us with them for as long as possible, but that’s something to consider especially if you have a lot of heavy assets like videos. It may not necessarily mean that we’re going to hit a hard limit and not be able to upload anything else. Rather it would mean exceeding the quota and increasing the overall price of the product. 

How much does it cost?

It’s hard to neglect that aspect. Having a good tool for storing an organization’s knowledge is important, but that’s also not a goal on its own. If it’s too expensive considering the company’s revenue, it doesn’t make sense to invest in it. It’s a balance between how much convenience you are going to buy, and how much burden you’re going to leave on the document editing people.

Takeaways

There are multiple aspects to consider and plenty of questions to ask when picking up the right tool for software documentation. These could be split into the following groups:

• Operational aspects:
  • cost
  • access management
  • storage capacity
  • is it available with other tools you use
  • migration
• Usage aspects:
  • extensibility
  • UX
  • performance
  • easy of use (shortcuts, commands)
  • number of supported components and asset formats
• Content aspects
  • what kind of docs are going to be covered
  • search
  • organizing content (labels, custom fields)