Summary

The provided content discusses the Documentation as Code (Docs-as-Code) approach in software development, emphasizing the integration of documentation with code in version control systems and the use of tools like Markdown, AsciiDoc, PlantUML, mermaid, Swagger Editor, and Confluence Publisher to maintain technical integrity and consistency.

Abstract

The Documentation as Code (Docs-as-Code) methodology is gaining traction in the field of software engineering. This approach treats documentation with the same level of importance as the code itself, incorporating it into the same tools and version control systems used for software development. By doing so, it ensures that documentation is kept up-to-date, version-controlled, and consistent in format. The article highlights several tools that facilitate this process, including Markdown and AsciiDoc for writing documentation in a lightweight, easily integrated format, PlantUML and mermaid for generating software architecture diagrams, Swagger Editor for defining and generating RESTful API interfaces, and Confluence Publisher for automating documentation updates within a CI/CD pipeline. The author also points out that this approach is not entirely new, referencing LaTeX as an early example, although it does not fully embody the Docs-as-Code philosophy. The article concludes by inviting readers to explore further Software Architecture topics through a list of related articles and to connect with the author on social media platforms.

Opinions

The author suggests that traditional documentation methods, such as using Microsoft Word, are less effective than the Docs-as-Code approach because they rely on WYSIWYG editors and manual formatting.
The author expresses a preference for lightweight markup languages like Markdown and AsciiDoc, noting their seamless integration with source code management (SCM) tools like GitHub.
PlantUML and mermaid are recommended for creating software architecture diagrams, with mermaid being particularly suited for frontend developers due to its JavaScript syntax.
Swagger Editor is highlighted as a valuable tool for rendering YAML files that specify RESTful APIs, allowing for the automatic generation of API interfaces.
The Confluence Publisher Plugin for Jenkins is presented as a solution for automating the update of Confluence pages in sync with deployment or other stages of the CI/CD pipeline.
The author implies that the Docs-as-Code methodology is superior in maintaining technical integrity and ensuring that documentation is reviewed and generated consistently alongside the software development process.

Documentation as Code Approach in Software Development

Documentation as Code aka Docs-as-Code is a popular approach in Software Engineering in which dev team treats documentation same as the code. It means, documentation is written in same tools as software is written. This philosophy brings some advantages like:

technical integrity: documentation is part of code and integrated to version control, CI/CD tools
documentation is written together with software
documentation can be reviewed in each sprint along with developed feature
documentation is automatically generated with consistent format

Documentation with for example Microsoft Word bases on WYSIWYG word processors, where writer formats the text himself. In Docs-as-Code tools, the text format is automatically generated as you write in lightweight text format.

One of the very first examples of Docs-as-Code can be considered LaTeX that many of us know from our University years. But this does not count really to Docs-as-Code mentality.

Markdown or AsciiDoc are great lightweight markdown tools that are enabling easy documentation and perfectly integrated to scm tools like GitHub. README.md is a perfect example every time you create a new git repository.

PlantUML is a perfect open-source tool for generating software architecture diagrams. This is a nice plugin also for Eclipse, VS Code, Intellij and working fine in all operating systems.

mermaid is a nice alternative to PlantUML with JS syntax. It adds some extra functionalities and comfortable to use for frontend devs.

Swagger Editor is a nice editor that renders yaml files that specify restFul APIs. Based on this specification yaml files, rest api interface can be automatically generated. Here is a nice example from swagger official site:

Nice alternative to this editor is redoc, which is in open-source and paid versions available. With enterprise version, you can have extra functionalities like documenting html format for non-dev colleagues.

Confluence Publisher Plugin from Jenkins can be used to update Conluence pages automatically with each deployment or any step of CI/CD pipeline:

If you are interested in more Software Architecture topics take a look at my other articles.

Relevant Articles:

P.S. You can connect with me on twitter or linkedin.