Software Documentation & PlantUML

Documentation as Code Documentation as Code (or Documentation-as-Code) is an approach that treats project documentation in the same way as source code. Instead of creating static documents in separate tools (such as text editors or wikis), documentation is written in versioned files, typically in human-readable and machine-processable formats (Markdown, AsciiDoc, etc.), and stored in the same repository as the code. Main Features Feature How it works in practice Versioning Each change to documentation generates a commit, allowing you to track who changed what and when, just like with code. PR Reviews Documentation changes undergo code reviews (PRs/MRs). This ensures quality and consistency, and allows developers to review the content before merging. CI/CD Integration Automated pipelines can validate syntax, generate documentation builds (HTML, PDF), and even publish to hosting sites (GitHub Pages, GitLab Pages, Read the Docs). Automation Scripts can extract information directly from the code (e.g., docstrings, comments, OpenAPI specs) and insert it into the documentation, reducing duplication and errors. Collaboration Anyone with access to the repository can contribute, use the same development tools (IDE, linters, formatters), and follow the same style conventions. Benefits Consistency – Documentation evolves alongside the code; API or behavior changes are reflected immediately. Quality – Code reviews enforce writing standards, spelling, and clarity, as do implementation reviews. Transparency – A complete change history facilitates audits and understanding of past decisions. 4. Scalability – Automation (generating diagrams, tables from real data) keeps documentation up-to-date without manual effort. Process Unification – Teams don’t need to manage two different tool stacks (one for code, another for docs). Popular Tools Hugo & Docsy1 – Static site generation that supports UML, OpenAPI, and other documentation. MkDocs (with Material theme) – Converts Markdown into static sites; integrates well with GitHub Actions. Sphinx – Uses reStructuredText (or MyST Markdown) and supports extensions to generate documentation for Python, C++, and other APIs. Docusaurus – React framework for documentation sites; accepts MDX (Markdown + JSX). Read the Docs – Service that hosts automatic builds of Sphinx/MkDocs from repositories. - GitBook, Docsify, Hugo – Other options for static website generation. Hugo & Docsy “Docsy is a pre-configured Hugo theme that provides the main features and behaviors needed to create a technical documentation website.”