This is a curated page of resources helpful to exploring and implementing a docs-as-code approach to technical documentation. You are strongly encouraged to submit a pull request including your own favorites!
At this point, I’m not going to list or explore source-control systems other than Git. It just doesn’t seem worth it. That said, you should understand why source control and version control are important and the philosophy behind their use.
-
Betterexplained’s "A Visual Guide to Version Control"
I wish I had read this series when I was first learning Git.
-
Git Immersion
Includes a great quickstart guide to help you get up and running on your own machine.
This is one of the controversial defining factors of docs-as-code; you don’t have to use a lightweight markup language to keep your docs in source and think programmatically. But as long as the language isn’t too light to include semantic markup (such as most forms of Markdown and most Wiki MLs), it’s hard to justify the added burden and expense of tag-based languages (HTML, DITA, Docbook, etc.).
I haven’t tried to hide it; I love AsciiDoc, even though I recognize its limitations and don’t find all of its syntax elegant or intuitive.
-
Asciidoctor.org
The prime resource for contemporary AsciiDoc, offered in Ruby and beyond.
-
Using AsciiDoc and Asciidoctor to Write Documentation
A great general purpose primer/quickstart. -
The Asciidoctor User Manual
Truly the gold standard of language documentation. Asciidoctor himself Dan Allen is arguably the best practitioner of the language he resuscitated in just a handful of years. -
AsciiDoc Writer’s Guide Another Dan Allen/Asciidoctor production. Also my favorite tech-writing style guide.
-
Awesome Asciidoctor Notebook
A compilation of excellent blog posts examining intermediate and advanced topics in AsciiDoc.
This is the only of the latest generation of static site generators I’ve tried seriously so far, owing largely to the jekyll-asciidoc plugin (Asciidoctor strikes again).
-
The official Jekyll site
This is a pretty great resource; I find myself using it as my primary reference.
You could be forgiven if you’ve started to suspect I have a bias for applications coded in Ruby programming language. It’s true: Git, Asciidoctor, and Jekyll are all Ruby gems.
However, quite unfortunately, I actually dislike Ruby and am a total newb at it. With my limited programming acumen, I find Ruby difficult to learn, though even I am able to tinker here and there. That said, these tools are all truly excellent, and there are a great many resources on Ruby, especially on StackOverflow, which is a pretty good place to start learning Ruby, and the place to go when you get stuck.
This tool is amazing. It is the near-perfect Rosetta Stone for markup languages and text-file formats, able to convert almost anything to almost anything else. It lacks any real framework and can require some heavy lifting to integrate, but Pandoc is the closest thing to docs in a box. Short of such programmatic applications, you can explore Pandoc simply by converting source files to alternate output formats from the command line.
For dealing with offline files, you really only need Pandoc, but below we share a few tools that will get you through special conversion challenges.
- AsciiDoc Processor Google Docs add-on
-
This tool will quickly and effectively output properly-formatted AsciiDoc markup for Google Docs.
- gdocs2md-html Google Docs script
-
This hacky-to-install but well-documented tool will convert your Google Docs handily to Markdown.
Here’s where things start to get hairy. The CCMS world seems to be dominated by DITA, IBM’s XML-based markup language for technical documentation. Since the DITA ecosystem is mostly closed-source, it may be a nonstarter for serious DocOps-minded hackers. But I do want to see more holistic systems such as DITA CCMSes, which help manage your docs and files in ways most of the raw flat-file publishing “systems” don’t even try.
In the spirit of promoting more concerted open source development in this space, I’ll research and list a number of proprietary CCMS platforms here here.
- Corilla
-
A techcomm CCMS that uses Markdown and a simple, friendly GUI for associating topics and files.
- AsciiBinder
-
An AsciiDoc-based publishing platform.
- DocumentUp
-
A Markdown-based publishing platform.
- Read the Docs
-
A popular platform that enables reStructuredText- and Markdown-based formatting.
- GitBook
-
Perhaps this platform’s coolest feature is the elegant editor they provide for free. It’s simple but effective for writing in both Markdown and AsciiDoc.
- LeanPub
-
LeanPub is the productization of the “Lean Publishing” strategy we’re basically following with this book, though Codewriting adds direct content contributions to the mix. LeanPub is a great way for authors to self-publish; it includes an e-commerce system that will pass along 90% of your book’s revenues, which I think is unheard-of elsewhere in tech publishing.
|
Tip
|
Don’t see your favorite platform here? Suggest it in the Issues for this GitHub project or in the |
- I’d Rather Be Writing
- Just Write Click
- Every Page is Page One
- Read the Docs
- hack.write()
- The Content Wrangler
-
Though not particularly docs-as-code oriented, this site occasionally features decent articles about tech writing strategy and tactics.