DEV Community

loading...

Continuous Integration for Documentation

adhistac profile image adhistac ・1 min read

In the software industry, documentation is started usually after a developer writes code and the bugs are fixed. This approach's prevailing problem is that documentation is an afterthought and long release cycles more likely result in inaccurate docs.

What we need to understand is that documentation is not overlooked; however, the workflow is. To document, you need to switch tools. Hence, this switch of context pushes the whole process of documentation to the very end. As of now, the integration of documentation in a continuous workflow is of utmost importance.

Continuous integration (CI) means code is continuously tested, integrated, and merged. While Continuous Deployment (CD) means code is continually deployed with each patch. For documents, CI and CD include the building, testing the content, reviewing, versioning, and publishing the full artifact for each patch.

When we treat documents like code, the integration of them becomes faster. Nowadays, source code based documentation generator like markup languages, latex, pydoc, and javadoc is gaining popularity. Documents like code are always versioned and stored in the version control system. Also, the artifacts for the documents are automatically generated. Furthermore, document files are meticulously reviewed and tested for their accuracy and functionality in the continuous workflow. Overall, there is less human intervention.

To sum up, this practice results in the creation of uniform documents. It also promotes collaboration with the developers by tracking each documentation mistake as a bug. So, applying the software engineering practice to documentation empowers developers to start documenting, which makes the collaboration convenient.

Discussion (0)

pic
Editor guide