How To Choose Your Documentation Tools

Choosing documentation tools that you use to write, maintain, and publish your documentation is an essential part of your documentation strategy.

Typically, selecting content management and authoring tools is a long-term commitment.

Also typically, it’s the least thought-out decision but the first one that’s actually made.

Teaser-Image_TDG-How-To-Choose-Your-Documentation-Tool-20260127-122911.svg

So let’s start with things you should remember:

Do not get swayed by a friend or a trend.
You’re not selecting just a writing tool.
You’re not selecting a tool that only serves writers. Documentation is a cross-team effort.
No content management system (CMS) will save you. But it sure can break you and make your life pretty miserable.
You don’t have to start with a full-fledged documentation tool. Choose a tool that’s flexible and can grow along with your changing needs.
A price tag can be misleading.
- Headless and open source often mean you’ll do the heavy lifting yourself. From integrations, through building a website, to coding in a paid search tool integration.
- Some tools are overpriced and/or overhyped.
- Beware of hidden costs (service fees, hosting fees, technical fees) that can add to an already hefty per-seat price tag.
It’s easy to get lured by the features you’ll never use. Buying a tool that has all the essentials, like SSO support, but is modular and can grow with you, might be a better option than paying tens of thousands of dollars for features you are unlikely to use.
Everybody’s got AI. But not AI tools are created equal.
It’s easy to box yourself in with a simple and cheap tool and then hit the wall pretty quickly.

Terminology conundrums

In this article, we’re using terms CMS (content management system), documentation tools, content tools, etc. interchangeably. Yes, there are conceptual differences. Sometimes, you may need several tools to accomplish the goal. What we focus on here is the sum of features your toolkit should have and why they’re important.

The CMS Selection Checklist

The following checklist is based on several real-life requirement analyses for a wide range of products, from routers through SaaS analytical tools to mainframes.

The checklist features best practice comments as well as questions that only you can answer based on your specific circumstances. The thing is, not many writers or information architects are asking themselves these questions.

Note for Confluence users

Over the years, we found out that Confluence and the wider Atlassian ecosystem (Jira, Jira Service Management, Marketplace apps, etc.) hit the sweet spot between features, flexibility, and learning curve, but also provide a remarkable bang-for-buck value.

Every single question and use case we outline on this page can be addressed within the Atlassian ecosystem. To learn more, see How Confluence Makes Documentation Faster, Easier & Collaborative.

Essential Characteristics of Your Toolkit

In this section, we discuss the essential characteristics and factors that you should consider at the beginning of your requirement analysis. Remember, price per seat is just one of the factors.

Features	Why you should consider it
Number of seats / price per seat	How many users do you need? What will it cost? What access do they really need? Don’t count just writers – include developers, subject-matter experts, QA engineers, product managers, and designers. Too many solutions sell author and “read only” licenses as a cheap but dysfunctional solution. You risk wasting time exporting pages as PDFs, text files, or sending emails to your peers just to get a review, then manually incorporating their comments. Or worse, you end up juggling countless branches, merges, and rebasing. There are hidden costs to 4-author and unlimited-reviewer licenses.
Cloud location and Cloud collaboration	Working on content locally, away from the cloud, or in a fork usually means that you’re working in a silo.
SaaS	SaaS isn’t perfect, but unless you have your own 24/7 support team to maintain your proprietary documentation setup, rebuild help sites whenever needed, and a robust online backup policy for all local installations, you will always wait for somebody else’s availability and/or discipline.
Storage	Check how much storage your SaaS tool’s target pricing tier offers. You don’t have to upload lots of audiovisual content, but 2 GB of storage for your documentation might run out pretty soon.
History	Does the tool keep the change history long enough? Many keep only three months of edits and saves, which may not suffice for typical writers, especially in regulated industries. Can you easily revert a page to a previous state without dependencies and conflict with other pages?
Is a help site part of your content tool?	Some documentation tools are strictly writing and content management only and expect you to handle creating the documentation or intranet site yourself from scratch. That adds costs – in money and resources – to create, maintain, and update a fully customized environment. In some tools, implementing versioning to the help site is a question of 5 clicks in Settings. In others, it’s a full scale engineering endeavor. A compromise is a modular approach, a CMS that you can easily expand with add-ons (plugins, marketplace apps). Finally, does a mobile version of your help site come standard? Or do you need to code it manually?
Number of documentation sites	How many documentation sites can you create for your products? Some allow you to only create one or two product documentation sites (help portals). Which is a problem if you have three apps in your portfolio.
Add-ons / apps / plugins	Many content management systems (CMS) are closed. You might be able to programmatically connect third party tools (support desk, work management tools, etc.) by ways of connectors that are often not free and require engineering assistance. However, even such a ubiquitous task as connecting Jira might be impossible. Not to mention dependence on multiple APIs. Some CMS, such as Confluence, are modular by design. Think of them as smartphones - whatever you need, there is an app for that and you can easily expand in-house features with apps (extensions, plugins) from a dedicated secure marketplace. But again, in some CMS tools, you can install apps just as easily as on your smartphone. On others, apps must be implemented programmatically.

Editor Requirements List

A content editor is where all the magic, aka writing, happens. Some editors are very user friendly, some require writers to know a specific syntax. These are not simply quality-of-life features. Characteristics of the editor will impact speed, usability, and the pool of contributors.

Features	Why you should consider it
WYSIWYG text editor	Crucial if your team includes non-technical users or if you prefer to write, rather than code, your documentation. The added benefit is that seeing and editing the page exactly as users would see it, improves your ability to think as the user, thus improving documentation. Inexplicably, some CMS systems decouple the text editor from the document structure. That means that you don't necessarily know where exactly the given content (page) would end up. This means, as a writer, you're losing crucial information context. You may also encounter CMS that don't make it possible to edit multiple pages at the same time, making it extremely difficult to play around with content to see what works and what doesn’t until you create a preview of the entire doc set.
Rich text	Typing HTML, XML, or Markdown syntax just to make text bold feels like using a typewriter in 2025. It makes onboarding harder, reduces the pool of competent documentation writers, and hampers collaboration.
Media support	Will you see the actual image or video on your editor's page, or just something like <file_menu.png>?
Macros, modals, panels	The tools should come with a comprehensive selection of formatting and functional elements - such as expand panels, code blocks, notes, warnings, etc.
Reusable content	There are disclaimers, sections of pages, images that you want to use repeatedly within your documentation. Reusable content makes sure that when the time comes to change a warning, you only change it once, on the original page, and the changes automatically propagate to every ‘copy’ of it.

Workflows, Approvals and Content Management

The following features will impact both short and long-term life cycle management of your documentation. For example, how you handle changes, updates, deprecations, and cooperation with other team members. You will also learn how to approach and use version control and conditional content that will make life easier both for you and your readers.

Features	Why you should consider it
Drag & Drop WYSIWYG structure editor	Can you move the pages just by drag-dropping them to a position in the navigation tree? Or are you working with a Windows Explorer folder structure and then manually assigning metadata to files to give them a place in the actual documentation structure? As a writer, you work both with the Content and the Context. The more atomized your content pieces become for you as a writer, the less context you can provide for your reader.
Workflow (draft > done) - page level	Can you indicate that the page content is in the draft stage? Automate status changes and publishing? Can you apply workflows to individual pages to update and publish them independently? Workflows should be ‘functional’, in other words, applying a specific workflow status should change what can/can't happen to your content within your CMS. This can work together with altering permissions based on specific roles your team members have.
Version control	Important if your documentation strategy requires semantic versioning (1.2, 1.3…). You should be able to freely create snapshots of your entire docs and make them available as independent versions.
Versioning - semantic	Semantic versioning support in your documentation tool allows you to release specific versions of your documentation that correspond to software release versions, such as 1.2.3, 1.2.4, etc.
Compare full-text page history	Easily track changes at the page or doc set level.
Conditional content (variants)	Imagine you have an app for Windows, MacOS, and Linux. Save time by authoring all three documentation variants from a single source, then publish them to your documentation site where users can choose which flavor of docs to use. Or, create public/internal variants and support feature segmentation (Free/Paid product variants). This isn’t about CMS permissions. It lets USERS choose the documentation variant they need, Support can share tier specific links, while you manage everything in one place. Conditional content capability is far from common in the world of CMS.
Single source editing and reviewing	Avoid exporting PDFs for stakeholders' reviews and comments. Use a tool where writing and reviews happen on the same page with controlled reviewer access.
Preview page content in context at any stage	Some tools don’t let you see content as your audience would until you publish it - albeit in the staging area. Again, we cannot be more emphatic about how context is important both for writing and for reading documentation.
Preview doc structure in the tool	See what readers would see after publishing.
Automatic cross-version link management	A good CMS ensures links from version 2.3 don’t point to version 2.2 pages. You shouldn’t have to fix this manually. The same applies to translations – you don’t want a German version linking to English.

Publishing and Internationalization (Localization)

Publishing is the moment when you expose your documentation to your audience. The form and method are important. This section discusses factors that will help you fine-tune your documentation delivery.

Features	Why you should consider it
HTML/XML export	Perfect for sharing docs with customers who need full offline access or want to white-label your docs for their customers.
PDF and Word exports	Many places require documentation in accessible electronic formats for offline use or printed copies. You might also need electronic archives for audits. Whether for convenience, compliance, or practicality, a polished PDF that you can create any time you want is the way to go.
Publishing (website)	Does your CMS come with a website hosting option and/or tooling? All-in-one solutions exist - you can make Confluence spaces public or, better still, you can easily create a website with our Scroll Sites Atlassian Marketplace app without writing a single line of code or taking care of hosting.
Localization support (XLIFF)	Managing your localization flow with XLIFF files saves time, money, and headaches. For more information, see https://en.wikipedia.org/wiki/XLIFF.
Accessibility	Accessibility features start in the editor but you need to make sure your help site is accessibility-friendly. For example, if a screen reader cannot see the content in the navigation tree, because your site doesn’t have one, it will be very difficult for a visually impaired user to browse the content.

Customizing and Expanding Your CMS

Some content management tools are closed. Some are ‘headless’ and expect you to do the heavy lifting. Some are modular. Customization can be both visual and functional, and help you with your actual documentation authoring and management, and your audience.

Customization of look and feel	Why you should consider it
Styling and customization	Lets you modify the documentation site to match your company's visuals. Basic customization should be point-and-click - whether for proofing or for teams that cannot rely on dedicated engineering resources. CSS customization is never bad if you want to take styling to another level.
JavaScript	Offers more customization and third party options.
Add-ons / apps / plugins	Expand stock features with third-party apps. Some tools are highly customizable in a non-programmatic way, some are closed gardens.
Secure marketplace to expand functionality	If your CMS is supported by a vendor-run secure marketplace, you'll have a very easy path to adding new features to your documentation life-cycle as your team grows. Verify vendors follow basic security policies. Some doc-as-code tools rely on open-source add-ons coded by small groups, which may not meet ISO/SOC standards, especially in regulated industries. Securing the infrastructure would be entirely up to you.
Custom domain	Can you host your docs on your own domain? Preferably without having to code and run the entire documentation website infrastructure.
API	If your CMS tool comes with its own API, you can securely integrate custom tooling. Explore if it’s possible to connect your favorite AI tool’s API with your CMS’s API and serve your selected content directly in your product.

Security and User Management

This section introduces new layers of choosing a documentation tool. Corporate security, technical maintenance of the tool, and the documentation team autonomy.

Features	Why you should consider it
User Authentication	You don’t want random strangers to edit your docs or read your drafts. You may also want to restrict documentation to internal users and/or your customers.
SAML SSO	It secures your authoring environment and lets you create internal documentation portals and intranet sites. SAML SSO is typically run by your IT/DevOps department for your whole company. Chances are that a CMS that supports SSO will be much easier to integrate into your company IT infrastructure and will be more secure. Many CMS tools only support SSO in their enterprise (and most expensive) tiers.
Permissions	Documentation is a team effort, but not everyone should edit articles. Most should have view or even comment rights. Meanwhile, that bonus policy page should stay hidden to all but five people 😉. A tool with broad access and easily manageable permissions assures that a documentation life cycle becomes a smooth team effort.
Manageable by your documentation team?	Can your documentation team manage the infrastructure within your enterprise? Can they update docs anytime without filing an engineering ticket and waiting two days for a response? Updating documentation should not depend on product or code updates. In 2025, you should be able to fix a typo in your authoring environment and publish the correction to your online site within minutes.
Technical support for your tool	DIY documentation tooling solutions lead to DIY support…
Working with external contributors	Sometimes it helps to work on documentation with people who don’t have paid seats – contractors, translators, or customers. Does the tool let you add them temporarily with limited access as guests at no extra cost?

Integrations and Universality

Documentation does not exist in vacuum. Neither should your content management tool. A lot of ad hoc communication can happen outside, integration with project management tools ensure process integrity. Similarly, ability to include active non-documentation formats (presentations, spreadsheets).

Tools	Why you should consider it
Slack	A quick way to speed up team communication while keeping your content central.
Jira and other project management tools	This is crucial, especially in the world of product documentation. Integrating your CMS with project management tools improves cross-team collaboration and improves visibility of documentation teams within the development workflow. Some tools offer such integration out of the box, some require programmatic implementation via connectors, some are truly standalone isolated tools. Confluence and Jira are made by Atlassian so integration is logical and runs really deep.
Google Docs and Office 365	Content management tools typically don’t come with spreadsheets and presentation makers. The ability to embed such formats natively and even make them editable directly from your CMS provides an enormous boost to productivity.
Google Analytics, etc.	The industry standard for online content analytics.
Search	Surprisingly, some documentation tools lack built-in search – you must buy and integrate a third-party solution or upgrade to a higher pricing tier. If you’re hosting your own documentation website, you must implement search both in your authoring environment and in the documentation site.
A one-trick pony?	Can you use your documentation toolkit for anything else? And if so… can you afford to pay for extra author seats? Companies often end up with a plethora of tools for specific teams. Documentation tool. Intranet tool. And of course, engineering must have their own programmatic solution for their content. Marketing and Learning too. All those need to be implemented, integrated, managed, secured, maintained…. And yet, all those share the majority of core content features. Reducing the number of tools will not only reduce cost and demands on resources, it will also greatly improve onboarding, training, and collaboration. Fewer tools means fewer security risks and easier user provisioning. Imagine, having the tool training content right in the actual tool and then using the same tool across the org. The tool may not work for everyone outside the box, but it should offer enough options so you can customize it for the needs of specific teams.