This is the first blog entry for the documentation for the Monorepo Boilerplate project that is currently in development. My first decision in creating the project is to start by outlining different documentation tools and deciding on which to move forward with.

The Options

After some initial research, it seems like there are quite a few good documentation tools out there that could meet our needs. The table below outlines the different tools and their benefits and considerations for our use case.

Tool Name Benefits Considerations
Gitbook ⭐
  • Mature product
  • Poor support
  • Focusing primarily on supporting paying customers - even then support is spotty
  • Redux is investigating alternatives for their documentation (they currently use gitbook)
docsify ⭐⭐
  • Doesn't require a build process - pure static implementation
  • Very simple configuration
docz ⭐⭐
  • declarative routing makes configuration very easy - routing is defined in the docs files themselves
  • The most minimal setup of all options
  • Allows for very easy use of react components in .mdx files
  • Small weird issues that haven't been addressed (i.e. not great product support)
  • Lacking full featured search functionality
docusaurus ⭐⭐⭐
  • Supported by facebook
  • Highly configurable
  • Powerful algolia search (requires hosted site for the site crawler)
  • Built with React and allows custom pages
  • Highly configurable
  • non-trivial directory structure and large number of required files
Gatsby ⭐⭐⭐⭐ I did not officially consider Gatsby. It would be a great candidate if we needed that level of configurability and customization, but it seemed like overkill. --

The Verdict - Docusaurus

When I finally got into the weeds with the different tools they started to show their true colors. I wanted to like docz the most but it ended up having issues that I felt like warranted caution in proceding with use. (See the considerations for docz above). My second choice was docusaurus largely for the powerful support community of Facebook and it turned out not to disapoint. It's easy to set up and use and allows for great customization, but isolates it when it's unecessary.