Software Alternatives & Reviews

Keeping Documentation Debt At Bay & Clients Happy

Recommended and mentioned products

  1. Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swag

    This library allowed us to write the API documentation in-place throughout the route definitions, and drf-yasg would render documentation in either the form of an OpenAPI schema or as an interactive Redoc/Swagger UI web page. This meant that we were generating documentation from our code and there was no extra developer steps to change documentation if a feature or route changed.
  2. Swagger is an open source RESTapi Documentation Tool.

    Our RESTful API was actually the easiest to document, because we were able to rely on third-party libraries from the start. It was a Python Django and Django REST Framework project that leveraged the drf-yasg OpenAPI generator library to create OpenAPI and Swagger compatible documentation.
  3. A free, static web host for open-source projects on GitHub

    Amongst the many neat features of cobra, we were able to extend the Markdown documentation generation feature which would create rich user documentation for each of the available commands. We would generate this documentation at release time and either deploy the static files as a GitHub Pages site, or integrate them with our generic documentation below. We made sure to always include older release documentation...
  4. Jekyll is a simple, blog aware, static site generator.

    This growth problem was easily manageable when we had just a few teams using the product, as many of those users had been with us since the start of the product and could use it moderately well. We had a page or two of loosely organized Jekyll documents that briefly explained how to get different environments up and running, and the users were expected to sort-of just figure out the rest.
  5. Go, also called golang, is a programming language initially developed at Google in 2007 by Robert...

    Our command line interface was a Golang binary executable that was based off of the cobra and viper libraries which made creating advanced CLIs very easy.
  6. Hugo is a general-purpose website framework for generating static web pages.

    We gave Hugo a shot next, and it provided some more validation and speed in terms of development time. Since the associated program is just a binary, it could be very easily installed on our machines and in workflows without much fuss.
  7. Easy to maintain open source documentation websites

    After jumping from documentation generator to generator, we finally settled on Docusaurus. It introduced a build step again similar to Hugo, but we found that the trade off was worth it, as Docusaurus brought a bunch of really nice features with it. Since everything was just React under the hood that could be customized, we naturally gravitated to it as we already had React experience.
  8. A magical documentation site generator.

    Docsify is a client-side only documentation generator. As a user requests a documentation page, it would fetch the associated .md file and render it all client-side. That meant that our documentation deployment process was simple again, as we could just push changes to the main branch and BOOM they would show up within seconds.