The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.
I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.
Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.
Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.
-
What are you documenting?
When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?
For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.
For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.
For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs.
-
What output(s) do you need? A website? A PDF? Word documents? Something else? All of the above?
I would add to these options: ePub, slide decks, and manpages (Unix terminal docs).
Only a few solutions will be ready-made for numerous output formats.
-
Who is doing the writing? Technical writers? Engineers? Marketing? Everyone? Just you?
The more contributors you have, the more it will cost to use a per-seat proprietary platform.
When it comes to “just you”, however, consider whether you will likely have to hand off the project someday, or if you will hire more writers or ever bring the developers in.
-
Who is doing the reviewing/approving, and how?
The more reviewers, the greater the need for a unified review platform. If drafts will be given detailed reviews/edits by subject-matter experts, make sure those SMEs have access to the review platform.
Proprietary tools like MadCap Central offer integrated reviewing platforms for non-writers.
Otherwise, most engineering teams already have a Git-based review system, so adopting that along with docs-as-code might be tremendously helpful.
-
Who is doing the design, and what languages/templating system do they know?
Here we are really talking about whoever is implementing the design. Most static-site generators, CCMS, and cloud-based CMS tools favor one or another templating engines (Handlebars, Jinja2, Liquid, custom XML, etc, etc). They all use HTML, CSS, and Javascript, and the templating engines have their own syntaxes.
I would not make this a core criteria of the tools I choose unless there is a strong preference for a given engine. Perhaps the more pertinent question is: What suitable/appealing documentation themes are already available for the tool? Or maybe, What tools support a given preferred theme?
-
What integrations, if any, do you require? For example, do you need to connect to Salesforce or another support tool?
The most common support tools are the ticketing systems and knowledge base CMSes of platforms like SalesForce, ZenDesk and FreshDesk. These notoriously do not play nicely with very many content platforms, but they integrate fully with their own help desk software.
If tight integration is needed, check the platform’s integration offerings. Building a custom integration is difficult and costly, and hybrid (ticket + KB) search may be impossible.
-
See also Question 16.
-
-
Who is managing the toolchain from a technical perspective, and what chain do they know (OS, programming language(s), scripting language)?
The person/team implementing the docs toolset is important, but consider that whatever they build will have to be handed down someday.
If your company is a Windows shop or light on engineering, most of the proprietary or cloud-based tools will be suitable and not require any kind of DevOps support.
-
Is there a monetary budget? How much?
Per-seat platforms cost a lot over the years but generally much less up front for setup and migration. Docs-as-code setups tend to cost a lot up front and very little thereafter.
Migrating (or newly authoring) your actual content to any new tool will be costly, mostly concerning in-house staff hours. On top of that, assembling your own toolchain and orchestrating the the migration will likely cost at least $25,000 (US) for a contractor or perhaps three or four times as much if you divert in-house development cycles.
-
Are you converting existing docs? If so, what format/system are they currently in?
Sticking with the same source syntax is a great option, if it works for you and a tool that suites whatever needs you’re shopping for will support that source.
If you currently use lightweight markup (Markdown, AsciiDoc, reStructuredText), converting to another such markup tends not to be too difficult.
Otherwise, if you’re switching either way between lightweight markup and XML-based markup, you will probably need to migrate by exporting to HTML and then to the new source format.
-
Do you want something with corporate support when you inevitably run into roadblocks, or are you comfortable rolling up your sleeves and DIY-ing it?
Lots of companies go many years with minimal maintenance overhead, once the docs system is setup well. It’s also unlikely you can expect much beyond troublshooting help from a subscription solution, and there is great variance in how extensible/customizable the different toolsets will be.
If you anticipate major changes that are not built into the platform you choose, expect to roll up your sleeves or pay a contractor to do it, and choose an extensible or open-source platform in the first place. Once you are working with a custom solution (as opposed to a popular platform), competent outside help is likely to be most expensive.
-
Do you have philosophical preferences? (It MUST be open source! It needs a solid community! It needs to be sponsored or maintained by a solid corporation or nonprofit.)
Great question; self-evident implications.
-
Are you locked in to a specific search provider?
If your organization already spends a lot on a given solution for application-data search, you will probably want to use that platform for your documentation indexing/search as well. Make sure your solution integrates well with the existing search tooling.
-
Where do you plan on storing your source documents? Git? Something else?
If you have a strong preference here, it is probably Git. I can imagine preferring a SQL (relational) database if you have those skills, but that doesn’t strike me as terribly advantageous in and of itself.
Otherwise, this consideration should be more about whether you can accommodate a given solution’s actual/existing sourcing setup, which for most CCMS and cloud solutions is in fact at least partly a SQL or other Git-unfriendly DB.
Some CCMS/proprietary solutions do use/support Git.
-
Do you want to write in a WYSIWYG environment, or do you want to use a text editor or IDE?
This is one of the key deciders for proprietary vs docs-as-code. If you need both HTML and PDF and you strongly prefer to use WYSIWYG, your best options are a DITA CCMS and a tool like Oxygen or tools like MadCap Flare or FrameMaker.
-
Will you need support for localization or internationalization?
This can be a major factor. Adding l10n or i18n to a docs-as-code solution can be very expensive. You might want to choose something that has this capacity built in.
Also consider that translation services may have preferences and restrictions with regard to how they will work.
-
Do you need to enable doc versioning?
Only a small subset of platforms have version management built in. Source versioning via Git is one thing, but publishing, serving, and offering navigation for multiple sequential revisions or multiple concurrent editions (including internationalization, etc), can be highly demanding. In truth, this will almost always require custom coding on top of a platform that is open enough to accommodate your organization or product’s particular needs.
-
Are there existing tools (like support software) that you could leverage?
If your support-ticketing system comes with a knowledge base CMS, you should seriously consider using it. Most such KB’s are pretty weak on features, but integration with the support system can be huge. Likewise, if the company’s corporate site has a CMS, it is worth considering, at least in the beginning. Some such platforms have decent extensibility into the tech-docs world.
Sometimes, going with the path of least resistance is the fastest way to get docs available to users, which really is the main goal.
-
See also Question 5 and Question 11.
-
-
Do you have any preferences? For example, do you want to write in Markdown or use DITA?
As with the implementation questions, also consider what is easy to hand down or recruit help. And I might add, strongly consider AsciiDoc instead of either of these more-popular standards.
For large-scale, enterprise, or otherwise complex documentation solutions, the candidate toolsets will most likely fit in one of two broad categories:
These types offer the most scalability and flexibility, and the best in each class support truly structured authoring. For enterprise-scale documentation challenges, it is probably best to choose one of these broad strategies, then choose a specific solution within that category.
Additional types that we will cover include:
Some tools that fit in these types may be at least potentially more powerful/flexible than they at first appear.
|
Note
|
Disclamer
I have no ties to any of the providers mentioned or listed in this guide.
While I am working on my own (free, open-source) framework and have a strong bias toward DocOps/docs-as-code solutions, I do not think they are optimal or even suitable for every situation, and I have tried to reflect that here.
My own solution is not mentioned, let alone promoted.
|
The docs-as-code/DocOps approach will be a series of open-source tools and maybe a freemium ops/hosting platform or two (GitHub, Netlify, etc). These solutions will tend to be:
-
free or low-cost licenses
-
more flexible and extensible
-
more challenging to set up
-
more expensive up front
-
easier/cheaper for more contributors (once onboarded)
A docs-as-code toolchain is generally cobbled together from available FOSS/freemium tools. The components will likely be:
-
a lightweight markup format (AsciiDoc, Markdown, reStructuredText, etc)
-
text/code editor (VS Code, Sublime Text, IntelliJ IDEA, Obsidian, Vim, etc)
-
static-site generator (Jekyll, Hugo, MkDocs, Docusaurus, Sphinx, Antora, etc)
-
hosting/review platform (GitHub Actions/Pages, GitLab, Netlify, Vercel, Dokploy, etc)
-
search (Algolia, ElasticSearch, Meilisearch, Lunr, etc)
Component/structured authoring platforms will be one or a few integrated tools and services that either install as GUI applications — usually for Windows only or browser-based. These solutions will tend to be:
-
more expensive, per-seat licenses
-
less flexible and extensible
-
less expensive setup
-
more challenging to customize
The components of a more GUI-based platform will be:
-
content authoring in WYSIWYG/GUI
-
XML sources (DITA, DocBook, or custom)
-
content review and approval within the same platform
-
content publishing to same platform
-
extensibility constrained by the platform’s own ecosystem
-
built-in support for localization and internationalization
-
built-in search or limited integration
Platforms in this category include:
There are several developer-friendly cloud solutions that are a decent mix of the two approaches.
They are most advantageous when at least part of the intended audience is developers, and especially if you have technical writers contributing to developer docs as well as end-user docs.
These platforms can be fairly expensive, but they tend to mix writer-friendly tools (WYSIWYGs, OpenAPI editors, GUIs, etc) with developer-friendly workflows (Git, Markdown, etc).
To the extent they are browser-based, these tools are probably the best for adding users, though in most cases it is costly to do so.
Some of the main options:
The main advantage of this category is the tight integration with support ticketing systems and customer service platforms.
The top contenders in this group are probably:
The final category of documentation platform is the help-authoring tool (HAT). These are meant for creating help files for desktop applications and GUIs.
The ones I see cited most are:
Certain conditions favor certain solutions. I have listed several scenarios in the first column of a table, then suggested one or more existing solutions or else noted that I don’t think a given “type” of solution is well suited for the situation.
Even if you see ✗, there might still be a viable solution for your use case.
These are rough guesses based on my own observation and speculation, and they exist mainly to nudge you in the direction you’re most likely to find a well-suited or optimal solution.
| Turnkey SSG | Turnkey Cloud | Desktop CCMS | Cloud CCMS | HAT / KB CMS | Custom DocOps | |
|---|---|---|---|---|---|---|
Lone developer (GUI) |
MkDocs, mdBook |
GitBook, Mintlify |
✗ |
✗ |
✗ |
✗ |
Lone dev (dev product) |
mdBook |
Read The Docs, Mintlify |
✗ |
✗ |
✗ |
✗ |
Lone writer |
MkDocs, mdBook |
Readme, GitBook, RTD |
✗ |
Paligo |
✗ |
✓ |
Team of writers |
Docusaurus, Antora, mdBook |
Readme, GitBook |
Flare, DITA |
Paligo |
ClickHelp, Doc360 |
✓ |
Mix of devs and TWs |
✗ |
✗ |
✗ |
Paligo |
✗ |
✓ |
There are several online resources that contain more exhaustive lists of the various tools available for technical documentation.
|
Note
|
I will probably move this guide elsewhere, but for now it is a living document and I am EAGER for feedback or additional recommendations in the comments. |
@briandominick nice!
Any particular reason you haven't included Material for MkDocs above? Especially in the table (next to MkDocs) and in the list of static site generators as well.