Docs Like Code: Collaborate and Automate to Improve Technical Documentation

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.

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.

For diagrams in Markdown files, there’s an extension called Mermaid, at https://mermaid-js.github.io.

The GitHub Flavored Markdown (GFM) specification provides what you read on GitHub README and other Markdown files in every GitHub repo.

Many docs-as-code aficionados have discovered the Netlify platform, which builds websites automatically and fits in well with the docs-as-code mindset. Since Netlify combines site previews and global deployment to a Content Delivery Network (CDN) with automated builds, it makes sense to use Netlify for building docs sites.

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.

push Move your local committed changes to a remote location,

pull request A method of submitting edits that compares your changes with the original.