Docs as Code - Living Documentation with Github

Docs as code (DaC) is a revolutionary approach that treats documentation as an essential part of the development process, like code itself. Imagine documentation that stays current, is easy to collaborate on, and integrates seamlessly with your existing workflows.

Have you ever inherited a codebase with cryptic comments and outdated documentation? Or have you tried out a new program or bought a device with little supporting documentation? We've all been there!

This article explores DaC principles and how to leverage Github, to build living documentation that empowers developers and users.

This methodology advocates for creating and maintaining documentation using the same tools and processes used in software development. This approach ensures documentation is as dynamic, collaborative, and versioned as the code.

Here’s how we can implement Docs as Code effectively using GitHub and various tools:

Why Docs as Code?

Traditional documentation often suffers from:

Outdated Information: Documentation quickly becomes irrelevant if not actively maintained.
Siloed Creation: Technical writers and developers work in separate worlds, leading to inconsistencies.
Limited Collaboration: Sharing and revising documentation can be cumbersome.

DaC tackles these issues by:

Version Control with Git: Track changes, collaborate on edits, and revert to previous versions when needed.
Markdown & Plain Text: Use human-readable formats like Markdown that are easy to edit and have version control.
Collaboration on Github: leverage pull requests and reviews to ensure high-quality documentation.

Embracing Docs as Code brings numerous benefits:

Consistency: Documentation stays in sync with code changes.
Version Control with Git: Track changes, collaborate on edits, and revert to previous versions when needed.
Collaboration: Everyone, from developers to technical writers, can contribute. The use of human-readable formats like Markdown makes it easy to edit. Leverage pull requests and reviews to ensure high-quality documentation.
Transparency: Version control allows us to track changes and revert when necessary.
Automation: Integrate documentation workflows into CI/CD pipelines for seamless updates.

Getting Started with Docs as Code on GitHub

1. Version Control with GitHub

Store your documentation in a GitHub repository. This setup leverages GitHub’s powerful version control features, making it easy to collaborate, track changes, and manage versions.

Issue Trackers: Manage documentation tasks with GitHub Issues.
Pull Requests: Review and discuss changes before merging them.
Branching: Use branches to work on documentation updates without affecting the main version.

2. Writing in Plain Text Markup

Use plain text markup languages like Markdown, reStructuredText, or Asciidoc. These formats are human-readable and can be easily converted to other formats.

3. Code Reviews for Documentation

Treat documentation changes like code changes. Use pull requests to propose changes and request reviews from your team. This process ensures high-quality, accurate documentation.

GitHub Copilot for Docs as Code

GitHub Copilot is an AI pair programmer that helps you write code and documentation more efficiently. Powered by OpenAI Codex, it provides context-aware suggestions as you type.

Why Use GitHub Copilot?

Explain Code: Generate documentation that explains complex code segments.
Seamless Coding Journey: Enhance productivity by up to 55%.
Contextual Assistance: Copilot understands your codebase and provides relevant suggestions.

How Does GitHub Copilot Work?

GitHub Copilot analyzes your codebase and context, offering suggestions and improvements. It’s trained on public code and can work with private repositories, continuously learning and adapting.

Versions:

Copilot Ghost Text: Inline code suggestions, including unit tests.
Copilot Chat: Ask questions about your code and get contextual answers.

Tools for Docs as Code

Vale Document Linter

Vale is a highly customizable linter that ensures your documentation adheres to style guides and best practices. It’s user-friendly for both writers and developers.

Alex.js: is a simple linter with limited functionality.
Acrolinx: is a highly customizable linter, that supports multiple styles.

DocToolchain

DocToolchain is an open-source toolchain that automates generating and publishing documentation. It integrates well with GitHub and CI/CD pipelines.

Docs as Code Process:

1. Quick Start and Automation: Developers create initial documentation alongside code.

2. Plain Text Markup: Use formats like Markdown for interoperability.

3. Collaborate on GitHub: Use issues, pull requests, and reviews to improve documentation.

4. Automate: Integrate documentation builds and tests into your CI/CD pipeline.

Benefits of Docs as Code:

1. Transparency: Track changes and contributions with Git.

2. Collaboration: Anyone can create pull requests or view edit history.

3. Automation: Approved changes are published automatically.

Tips

Technical writer approval is required before publishing changes to ensure quality. To avoid delaying deployments, keep documentation in its branch, allowing tests to run only on the documentation changes.

Overcoming Challenges

Docs as Code helps overcome common documentation challenges:

1. No Time: Integrate documentation into the development process.

2. No Incentive: Encourage contributions by making it part of the workflow.

3. No Culture: Foster a culture of shared ownership between developers and writers.

Conclusion

Integrating Docs as Code into your workflow brings numerous benefits and ensures your documentation evolves alongside your code. Tools like GitHub Copilot, Vale, and DocToolchain streamline the process, making it easier for everyone to contribute and maintain high-quality documentation.

By following these practices, we can create a collaborative, efficient, and sustainable documentation process that supports the development and use of our software.