Docs Like Code: Collaborate and Automate to Improve Technical Documentation

one repo builds one deliverable, such as a docs.example.com site with all the documentation in a single repository. This pattern works well for self-contained subdomain websites like a developer portal or a single product docs site.

As one configuration you could set up a separate branch to publish the docs, which is a setting available in GitHub Pages. Typically this branch is called the gh-pages branch. You can also publish the docs with the exact branches and release tags as the code itself. This release synchronization is useful when the code and docs need to remain in syn

If developers are struggling to write docs in their repo, consider a separate repo for docs. But, if technical accuracy is the higher priority, keep the docs in the dev repo

Users. The way that you organize your information must not detract from the user experience. Think about how users will read each page, navigate through the site, and find what they need.

To decide whether to keep docs in the dev repo, use a single docs repo, or use multiple docs repos, consider your users, contributors, reviewers, content size, automated tests, deployed docs, and translated docs.

How do you know when to make a single deliverable from one repo or make a large website from multiple repos? The way that you organize information influences how you can present it to readers.

To help contributors form a mental map of the docs, you might synchronize the way that you organize source files with the organization of your site. If you have a simple product, a single repo that contains both the code and docs can be the easiest.

AsciiDoc can produce more outputs than Markdown “out of the box” including print, ePub, and slide layout, unlike Markdown which was never designed for print or ebook outputs.

AsciiDoc provides another markup language so that writing is “as simple as writing an email” with lightweight, easy-to-memorize (and read) syntax.