Choosing a docs tool

Daryl White
Choosing a docs tool

Credits:

In the Write the Docs Slack community, folks often ask how to go about deciding what documentation tool or set of tools is the right one to use. I have taken to replying often with a series of questions, instead of answering.

Why the Socratic method? Because tooling for docs is a very, very circumstance-specific choice. No one answer is correct. As I have often said in Write the Docs and elsewhere, I firmly believe that a good technical writer can create great docs with pretty much any toolset. Yes, even Microsoft Word, though we might shudder while doing so.

One time when I rattled off a list of questions to someone asking this question, several community members suggested I post my list somewhere so that it could be retrieved. (Write the Docs uses the free Slack plan, limited to 90 days of history.) This post is long overdue, but here it is.

The first set of questions are the ones I initially suggested in the conversation. The second set of questions were provided by another Slack community member, and I thought well worth including in this post.

Questions to ask when choosing a docs tool

  1. What output(s) do you need? A website? A PDF? Word documents? Something else? All of the above?
  2. Who is doing the writing? Technical writers? Engineers? Marketing? Everyone? Just you?
  3. Who is doing the reviewing/approving, and how?
  4. Who is doing the design, and what languages/templating system do they know?
  5. What integrations, if any, do you require? For example, do you need to connect to Salesforce or another support tool?
  6. Who is managing the toolchain from a technical perspective, and what chain do they know (OS, programming language(s), scripting language)?
  7. Is there a monetary budget? How much?
  8. Are you converting existing docs? If so, what format/system are they currently in?
  9. 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?
  10. 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.)
  11. Are you locked in to a specific search provider?
  12. Where do you plan on storing your source documents? Git? Something else?
  13. Do you want to write in a WYSIWYG environment, or do you want to use a text editor or IDE?
  14. Will you need support for localization or internationalization?
  15. Do you need to enable doc versioning?
  16. Are there existing tools (like support software) that you could leverage? It’ll be much easier to lean into something the company is already invested in than to try to bring in something new. And while no one really wants to write in Salesforce Knowledge or Microsoft Word, I am strongly convinced that any tool can generate great docs. Likewise, every tool demands compromises and sacrifices.
  17. Do you have any preferences? For example, do you want to write in Markdown or use DITA?

Update: Brian Dominick has gone through each of the above questions and added his own commentary, thoughts, and expansions to them. He then goes on to offer his thoughts on possible paths to consider after answering the questions, based on how you answered them.

Check out his post on GitHub Gist: https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef

Questions suggested by other tech writers

  1. Will the code examples live in the same repo or another repo?
  2. How will the code examples be incorporated in the docs?
  3. How do you keep the code examples up-to-date?
  4. How do you test the code examples?
  5. What programming language(s) will you support?
  6. What’s the process of updating a code example and the explanatory text in the docs?
  7. I’ve also been gobsmacked by naming changes, so another question I often ask is: Does the doc build process need to support substitutions? (Yes, please, is always my answer!)