Documentation as Code — Adventures with DocFx
One of the growing topics in technical authoring over the past few years has been Documentation as Code — a philosophy that “you should be writing documentation with the same tools as code”, rather than it being an awkward, disjoint part of your work.
We wanted to get an idea for how Documentation as Code could be useful within Redgate. Our recent project to make Redgate’s Product Development Progression Framework public gave the perfect opportunity, while also letting us get some hands-on experience with Redgate’s Honeycomb design system and tools.
Which tool to use?
As with anything, there are loads of Documentation as Code toolchains to pick up.
Without any clear or restrictive requirements, we wanted a reputable tool that would help us focus on the documentation as code approach rather than the tooling.
DocFx is a Microsoft-maintained tool, apparently popular for both customer-facing product documentation and internal documentation. It’s also used by others, like tool developer Infragistics, showing some flexibility to the tooling.
We can’t promise this is a “best of breed” tool, it’s shown plenty of promise in our experiments so far.
How did it go?
First, changing the documentation is a breeze. We followed the DocFx “Getting Started” tutorial and had an initial site together in no time. With some hosting support from our internal ITOps team, we were had a site up and running in an afternoon.
We were able to make changes in our tools of choice — VSCode, as it happens — and we were able to update, preview, and test our work without needing to publish it.
By setting up a continuous deployment pipeline — which took about half an hour — we’re able to get any documentation changes live in seconds. No need to remember URLs, hunt for login details, and so on.
Styling and layout options are limited out of the box, but this is balanced with a rich templating language and powerful plugin architecture. This let us apply Redgate’s existing Honeycomb styling without much effort (although we have some room for improvement there!).
Managing the documentation in GitHub gave easy access to collaboration tools we’re used to. Pull Requests have already proven invaluable for reviewing each other’s changes, and GitHub Issues is an excellent place for tracking outstanding work.
Perhaps not everyone at Redgate is comfortable with Github, but it’s already our most widely used platform for working collaboratively. Github themselves publish excellent getting started guides for their online platform, and our internal Engineering Academy offer some excellent training on using the git commandline
It’s early days, but we’re optimistic that Documentation as Code is a philosophy that we could get a lot of value from.
The tooling seems mature to adopt, easy to use, and it could really enable treating our software and documentation as parts of the same user experience rather than two separate deliverables.
Would you like to know more?
I’m no expert, but docslikecode.com was an excellent resource to get me thinking about Documentation as Code. I’d definitely recommend it to others who’re interested in this way of working.
For the tool itself, the DocFx documentation (itself maintained using DocFx) is an excellent place to start.
