Docs Like Code: Collaborate and Automate to Improve Technical Documentation

In repos that represent online docs, you can make the main and gh-pages branches identical with a simple configuration setting. Then, you treat gh-pages as if it were the main branch, and you continuously publish with a simple centralized workflow.

Without any sort of outside continuous integration (CI) tooling, you can use the gh-pages branch that GitHub provides for actual publishing. Using the gh-pages branch means that your workflow needs to include merging to gh-pages at specific times for publishing purposes.

When docs are integral to the code, the docs workflow must match the development workflow because the collaborators are using the workflow that is best for that repo.

If docs are in their own repo, you can version and release them separately from the code. You can choose a centralized, feature branch, or forking workflow.

if you are using GitHub, consider using the main branch only for both editing and publishing. This tactic works well if you are constantly publishing and want the main branch to consistently reflect the current state of the docs.

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.

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 (main) to integrate features.

Feature branch. All feature development takes place in a dedicated branch instead of the main branch. This encapsulation makes it easy for multiple developers to work on a particular feature without disturbing the main code base. It also means that the main branch never contains broken code, which is an advantage for continuous integration environm

Centralized. Work in a central branch, typically named main. Always push changes to that branch when working with others.