Docs Like Code: Collaborate and Automate to Improve Technical Documentation

developers shouldn’t arrogantly think their code is all that matters, and docs don’t matter because their users can “read the code.” We can all think of examples of failures caused by a lack of empathy.

the docs must be included in the definition of done. To get to that definition, it makes sense to use the same tools and build chains if these tools help with those shared goals.

Tightly integrated development and docs teams likely share goals like performance, efficiency, and customer satisfaction.

issue A way to submit a suggested improvement, defect, task, or feature request to a repo.

upstream The primary label for the remote URL indicates the original repo where changes are merged. The branch, or fork, where you do your work is called downstream.

When we say treat docs as code, we mean that you: Store the doc source files in a version control system. Build the doc artifacts automatically. Ideally, run automated tests on the docs. Ensure that a trusted set of reviewers meticulously reviews the docs. Publish the artifacts without much human intervention.

A commit is an individual change to a file or set of files. Every time that you save a file or a set of files, Git creates a unique ID, also known as the SHA or hash, that tracks the changes. Commits usually contain a commit message, which is a brief description of what changes were made.

An online, live editor is available at https://mermaid.live/ where you can see the diagram rendered side-by-side with the Mermaid graph code.

downstream A label for a remote URL, where a remote represents a place where code is stored.