The Importance of Technical Documentation

One of the most relevant factors in the self-development of humanity is the discovery of writing. The information learned is passed on from generation to generation through writing. Aware of this, Zaleos demonstrates the same precision as when developing its software while creating its documents.

Why is technical documentation key?
Although software companies don't usually have documentation as a high-priority topic, at Zaleos, we consider it a very important one. Our Definition of Done (DoD) means development can be done, only if it is TESTED, IMPLEMENTED, and DOCUMENTED.

Zaleos believes good documentation culture helps with long-term team efficiency. It allows tools, products, features, or concepts to be learned by individuals without requiring too much mentoring or supervision. For instance, this helps us a lot in the onboarding processes, or when the client needs to use something new: once created, it doesn't require too much time or resources from us, and it scales.

Text-based documentation

Documentation can be classified into Binary and Text-based documents. Since we're all Software Engineers, we create our documentation using text-based formats. Text-based documents are readable in any text editor, but also from any IDE. From the technical perspective, we can treat documentation as code, re-using the same Software workflows we're already familiar with. Peer validation using pull requests is great also for docs. Following we describe the two main text formats Zaleos has used so far:

reStructuredText (RST)
When working with the RST text files, we've mostly used Sphinx as the documentation generator tool. This is a great direction if there is a need to generate high-quality final user manuals, which are usually provided in PDF. Sphinx also generates documentation in multiple formats, including EPUB, HTML - or even MAN pages. We've mainly used the popular Read the Docs Sphinx Theme (with some proprietary Zaleos additions) to show clients how cool their docs are ;-)

Markdown (MD)
Internally, we work with MD text files in the Git repos (Github renders it nicely) or when using a static-web generator such as Hugo. This is a great direction if there is a need to generate good documentation that needs to be accessible only using a browser. The main use case is to generate online product documentation or development documentation. We created some Hugo proprietary themes for white labeling.

Restful APIs documentation
We use REST APIs a lot and we document them using the OpenAPI format. The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition for describing, producing, consuming, and viewing RESTful web services. There are a lot of Open Source tools to read and manipulate these specifications (or even to generate them from source code). We mainly use redoc to generate nice HTML-based documents from our "openapi.yaml" files!

Static checking & Linting

As a quality-driven Software Craftmanship shop, we also like to lint and static-check (as much as possible) our docs. We've created some internal tools to validate documents that run in Continuous Integration (CI) and check for well-formed release history entries for instance. Also, OpenAPI facilitates linting. The following example is an example of this usage:

openapi lint --config <path-to-lint-file> <path-to-openapi-index-file>

If Open API doesn't catch any warning or error, you should see a valid message!

Conclusions

At Zaleos, we're interested in creating processes that scale. Shared knowledge is one of them, it requires more time but it definitely pays off: thinking long-term, not only saves resources and money but also empowers a self-learning attitude. High-quality docs are - and will be - always part of our DNA.