With the range of software documentation tools available it’s difficult to know where to start.

I recently compared available documentation tools to determine which are best suited for a project I’ve been working on. What follows is a summary drawing from my own practical experience working as a technical writer while considering perspectives of others working in the field.

Summary Video

Background: Software Documentation & Tooling

Software products require technical documentation for users. For many SaaS companies, effective API documentation is essential for growth as it enables external developers and third parties to implement solutions independently without relying on internal development resources while minimizing support through training and customer service.

Authoring tools are generally used to create and publish documentation as web applications. The general minimum requirements for such tools include: internationalization (i18n), code samples in various languages, version control, and generation from OpenAPI specifications. Effective documentation authoring applications should foster a positive user experience for all stakeholders. Support for the addition of video content or interactive elements is often an added benefit.

There are various open source solutions for new authoring tools including Markdoc, Nextra, Gatsby, MkDocs, and more. The ideal solution is easy to use, visually appealing, adaptable, and meets all the minimum requirements of the organization and its users. Amid the range of choices, companies often struggle choosing a documentation tool that is fit-for-purpose.

Docs-As-Code

Docs-as-code means “writing, testing, publishing, and maintaining documentation using the same tools developers use for software code” [1]. With docs-as-code, documentation is managed in the same way as software code. This involves the following:

• Writing content with markdown files in an IDE.
• Version control system to store and version it.
• Automated testing.
• Build and deploy system.

Creating documentation is a multiphase process that involves identifying user needs, creating a plan, drafting, editing, and publishing content [3]. Although the tool directly touches on the latter three (drafting through to publishing), it is the central element throughout. The tool impacts essential non-tangible aspects such as user/employee satisfaction and quality perceptions.

Tooling

Several options for documentation tooling exist. They differ based on the following:

• Tech stack and development frameworks used.
• Features and plugins.
• Starter repos and ease of set up.

I compared eight tools that are widely used in industry. The eight were narrowed down from web research. For each tool, approximately 1-2 hours was spent conducting a feasibility trial consisting of the following steps:

1. Reading the website to determine background information, technical overview, and available resources.
2. Downloading/developing a starter repository that includes all the minimum requirements: internationalization, code samples in various languages, version control, and OpenAPI specifications.
3. Adding markdown content and custom styling. During the process, a qualitative assessment was conducted (using note taking), outlining what went well, challenges, and roadblocks. The table below provides a summary of the tools with advantages and disadvantages of each.

Tool Comparison

Tool	Description	Advantages	Disadvantages
Markdoc	Open sourced by Stripe in 2022. Integration with framework of choice: Next.js, React	- Newly released and widely used - Extensible and customizable	- Set up and default starter repos not as straightforward as other tools
Docusaurus	Open sourced by Facebook in 2017. MDX based. React + Node static site generator. Angolia for search and Crowdin for translations. Versioning support.	- Quick setup: starter templates / easy to get started - Regular product releases - Widely used - Lots of features & plugins available	- Limited to React - No built in feedback component - Plugin integration not always straightforward
Nuxt Content	Module that provides a file-based layer to Nuxt stack. Based on Vue components	- Widely used; built/maintained by Nuxt Core team	- Setup not as quick as Docusaurus
Nextra	From Next.js creators in 2020. Based on MDX.	- Syntax highlighting, i18n creation, out-of-the-box text search	- Less featured than some others (e.g., Docusaurus)
VuePress	Vue-powered static site generator.	- Default theme for quick setup - Ability to use Vue inside md files (for dynamic content)	- Not updated as often asthose from larger orgs (Markdoc, Docusaurus)
MkDocs	Popular Python SSG. YAML file configuration.	- Available themes for quick setup - Easy to customize	- Not a SPA
Docsify	Vue compatible SSG	- Lightweight - Plugins	- Not a SPA - Templates / themes are minimal
Gitbook	Documentation platform	- Widely used - PDF support - Rich Plugin system - Content editor for authoring	- Shifting from open source to product - Only free for open-source teams

Rating

Each tool was given a rating from 0-4 based on criteria which included the following:

• Tech stack that is a fit for internal tech teams.
• Features and plugins.
• Ease of use and setup.

One additional requirement is that the tooling is maintained as an ongoing project that is widely used in the industry. A maintained, widely adopted project allows for technical support, sharing best practices, and regular updates.

Below are the ratings assigned to each tool.

Markdoc	★★★☆
Docusaurus	★★★★
Nuxt Content	★★★★
Nextra	★★★☆
VuePress	★★★☆
MkDocs	★★☆☆
Docsify	★★☆☆
GitBook	★☆☆☆

Based on the rating, Docusaurus and Nuxt Content were deemed the best suited. These tools are based on React and Vue, respectively, and offer an option based on the preferred framework of the team.

Conclusion

Organizations often struggle finding the right tool for their documentation. I assessed eight different tools to be used in a docs-as-code workflow for a SaaS company. Each tool was tested against the minimum requirements and the advantages/disadvantages of each were noted. A rating of 0-4 was assigned to each. Two tools, Docusaurus and Nuxt Content came out with the highest ratings.

For the given context Docusaurus is recommended as a documentation tool. Docusaurus offers easy set up and is based on React, which is widely used. As a maintained, open source framework, Docusaurus also offers updates and resources.

References

[1] R. Krátký, ‘DevOps meets Docs: Documentation as Code’, OSSummit Europe, 2018. [Online]. Available: https://events19.linuxfoundation.org/wp-content/uploads/2017/12/DevOps-Meets-Docs-Docume ntation-as-Code-Robert-Kratky-Red-Hat.pdf

[2] E. Holscher. “Docs as Code”. Docs as Code. https://www.writethedocs.org/ (accessed Aug 1, 2023).

[3] J. Bhatti, Z.S. Corleissen, J. Lambourne, D. Nunez, and H. Waterhouse, Docs for Developers: An Engineer’s Field Guide to Technical Writing. Berkeley, CA: Apress, 2021.

[4] G. Bine, ‘Docs as Code and DITA’, TCUK, 2019. [Online]. Available: https://istc.org.uk/wp-content/uploads/2021/11/George-Bina-%E2%80%93-Docs-as-Code-and-DITA.pdf

[5] Begley, Niklas. “Why you should consider using docs-as-code”. Docave. https://www.doctave.com/blog/2021/08/30/why-you-should-consider-docs-as-code.html (accessed Jul 15, 2023).

[6] NuxtJS. “Content made easy for Vue Developers”. NuxtJS. https://content.nuxtjs.org/ (accessed Jul 15, 2023).

[7] Meta Platforms, Inc. “Docs.” Docusaurus. https://docusaurus.io/ (accessed Aug 1, 2023).