Keeping Documentation Debt At Bay & Clients Happy

1

Swagger UI

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.

#API Tools #APIs #Documentation 44 social mentions

2

swagger.io

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.

#API Tools #APIs #Documentation 81 social mentions

3

GitHub Pages

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 for users who were not on the latest CLI version.

#Static Site Generators #Cloud Computing #Blogging 466 social mentions

4

Jekyll

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.

#CMS #Blogging #Blogging Platform 180 social mentions

5

Go Programming Language

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.

#Programming Language #OOP #Generic Programming Language 292 social mentions

6

Hugo

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.

#Static Site Generators #Blogging #Blogging Platform 354 social mentions

7

Docusaurus

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.

#Documentation #Documentation As A Service & Tools #Static Site Generators 192 social mentions

8

Docsify.js

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.

#Documentation #Documentation As A Service & Tools #Knowledge Base 17 social mentions