# Docs Like Code
Author:: Anne Gentle
## Highlights
> We believe in collaborative writing and reviewing, and in using development tools for docs to bring dev and docs closer together and to push the edges of imaginary boundaries. ([Location 117](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=117))
> When we say treat docs like code, we mean that you: Store the doc source files in a version control system. Build the doc artifacts automatically. Ensure that a trusted set of reviewers meticulously reviews the docs. Publish the artifacts without much human intervention. ([Location 138](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=138))
> Webhooks, or ways to trigger an automatic action, have played a large part in the successful integration of GitHub with other tools such as Slack, Jenkins, and email. Because webhooks send an HTTP payload to a preconfigured URL, GitHub can be used to do a multitude of tasks from builds to backups to deployments. ([Location 175](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=175))
> Split deliverables into parts that encourage small but mighty contributions. One person no longer needs to own an entire deliverable. ([Location 195](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=195))
> When you fix a doc bug, you reference that bug in the commit message to help reviewers judge whether the doc fix solves the stated problem. ([Location 197](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=197))
> Learn enough about web development to be dangerous and create beautiful, modern docs. ([Location 201](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=201))
> Keeping docs and code together also saves time and keeps context-switching to a minimum. ([Location 219](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=219))
> Chris Anderson, editor-in-chief at Wired Magazine, popularized the term long tail to refer to the phenomenon of the rise of the niche. For example, Amazon and Netflix earn a larger percentage of their profits from rentals and purchases of relatively obscure, niche books and movies (low-frequency events) than from rentals and purchases of best sellers and blockbusters (high-frequency events). This same model can be applied to technical docs: the niche, or long tail, docs are constructed from obscure knowledge gathering and hard-to-find information. ([Location 226](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=226))
> Make beautiful docs By treating docs like code, you enter a community that truly wants beautiful docs sites. We want widely accepted tooling that is built in the open and shared by developers and writers alike. ([Location 261](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=261))
> The Read the Docs theme is often referred to as a “gold standard.” The theme is responsive for mobile devices, has an expandable table of contents, and has a best-in-class version implementation. The source code for the Sphinx theme is available on GitHub. ([Location 268](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=268))
> Read the Docs hosts docs, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. We support webhooks so your docs get built when you commit code. Version control enables you to build docs from tags and branches of your code in your repository. ([Location 282](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=282))
> By treating docs like code, you open up possibilities for automation, continuous integration, deployment to web servers, and lights-out docs service for around-the-clock support. ([Location 291](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=291))
> If you must freeze the docs at a certain point to ensure that teams can translate without worrying about subsequent doc changes, you might split docs into a separate repo so that you can version the docs separately from the code. ([Location 366](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=366))
> To evaluate an API’s complexity, multiply how many methods it has by how many parameters, headers, and error codes each method has. Then, match the number of assigned development and docs resources to the API’s complexity. ([Location 432](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=432))
> Although wikis don’t meet all the criteria of a docs-like-code framework, they do provide a simple and collaborative authoring environment with a low barrier to entry. ([Location 548](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=548))
> Centralized. Work in a central branch, typically named master. Always push changes to that branch when working with others. ([Location 607](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=607))
> Feature branch. All feature development takes place in a dedicated branch instead of the master branch. ([Location 609](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=609))
> It also means that the master branch never contains broken code, which is an advantage for continuous integration environments. ([Location 612](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=612))
> Gitflow. Work in feature branches, but have agreed-upon guidelines for branch interaction. Forking. Work independently in a fork of the repo. Merge as often as you like to your fork. Request merges through pull requests to the centralized repo (master) to integrate features. ([Location 614](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=614))
> Realize that the further the docs are from the code, the more difficult it can be to keep in sync. Think about creating a culture where code changes don’t merge without corresponding doc changes. ([Location 625](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=625))
---
Title: Docs Like Code
Author: Anne Gentle
Tags: readwise, books
date: 2024-01-30
---
# Docs Like Code
Author:: Anne Gentle
## AI-Generated Summary
None
## Highlights
> We believe in collaborative writing and reviewing, and in using development tools for docs to bring dev and docs closer together and to push the edges of imaginary boundaries. ([Location 117](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=117))
> When we say treat docs like code, we mean that you: Store the doc source files in a version control system. Build the doc artifacts automatically. Ensure that a trusted set of reviewers meticulously reviews the docs. Publish the artifacts without much human intervention. ([Location 138](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=138))
> Webhooks, or ways to trigger an automatic action, have played a large part in the successful integration of GitHub with other tools such as Slack, Jenkins, and email. Because webhooks send an HTTP payload to a preconfigured URL, GitHub can be used to do a multitude of tasks from builds to backups to deployments. ([Location 175](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=175))
> Split deliverables into parts that encourage small but mighty contributions. One person no longer needs to own an entire deliverable. ([Location 195](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=195))
> When you fix a doc bug, you reference that bug in the commit message to help reviewers judge whether the doc fix solves the stated problem. ([Location 197](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=197))
> Learn enough about web development to be dangerous and create beautiful, modern docs. ([Location 201](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=201))
> Keeping docs and code together also saves time and keeps context-switching to a minimum. ([Location 219](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=219))
> Chris Anderson, editor-in-chief at Wired Magazine, popularized the term long tail to refer to the phenomenon of the rise of the niche. For example, Amazon and Netflix earn a larger percentage of their profits from rentals and purchases of relatively obscure, niche books and movies (low-frequency events) than from rentals and purchases of best sellers and blockbusters (high-frequency events). This same model can be applied to technical docs: the niche, or long tail, docs are constructed from obscure knowledge gathering and hard-to-find information. ([Location 226](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=226))
> Make beautiful docs By treating docs like code, you enter a community that truly wants beautiful docs sites. We want widely accepted tooling that is built in the open and shared by developers and writers alike. ([Location 261](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=261))
> The Read the Docs theme is often referred to as a “gold standard.” The theme is responsive for mobile devices, has an expandable table of contents, and has a best-in-class version implementation. The source code for the Sphinx theme is available on GitHub. ([Location 268](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=268))
> Read the Docs hosts docs, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. We support webhooks so your docs get built when you commit code. Version control enables you to build docs from tags and branches of your code in your repository. ([Location 282](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=282))
> By treating docs like code, you open up possibilities for automation, continuous integration, deployment to web servers, and lights-out docs service for around-the-clock support. ([Location 291](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=291))
> If you must freeze the docs at a certain point to ensure that teams can translate without worrying about subsequent doc changes, you might split docs into a separate repo so that you can version the docs separately from the code. ([Location 366](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=366))
> To evaluate an API’s complexity, multiply how many methods it has by how many parameters, headers, and error codes each method has. Then, match the number of assigned development and docs resources to the API’s complexity. ([Location 432](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=432))
> Although wikis don’t meet all the criteria of a docs-like-code framework, they do provide a simple and collaborative authoring environment with a low barrier to entry. ([Location 548](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=548))
> Centralized. Work in a central branch, typically named master. Always push changes to that branch when working with others. ([Location 607](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=607))
> Feature branch. All feature development takes place in a dedicated branch instead of the master branch. ([Location 609](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=609))
> It also means that the master branch never contains broken code, which is an advantage for continuous integration environments. ([Location 612](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=612))
> Gitflow. Work in feature branches, but have agreed-upon guidelines for branch interaction. Forking. Work independently in a fork of the repo. Merge as often as you like to your fork. Request merges through pull requests to the centralized repo (master) to integrate features. ([Location 614](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=614))
> Realize that the further the docs are from the code, the more difficult it can be to keep in sync. Think about creating a culture where code changes don’t merge without corresponding doc changes. ([Location 625](https://readwise.io/to_kindle?action=open&asin=B08KY82ZSB&location=625))