As a technical leader at Rackspace during a docs modernization effort, I want to respond to Tom Johnson’s recent pointer to the developer docs site as an example of treating docs like code. Not just specifically for the “will it scale” questions, but for the questions I have fielded and continue to answer. Believe me, “Will it scale?” is the least of your concerns in a complex overhaul of attitudes, processes, tooling, and expectation setting.
I’m sure modern docs are not going to work for all projects and all people and all processes, but since I have first hand experience I thought it would be helpful to talk about it.
In case it helps, let’s describe the disruptions at the heart of the movement. You can see that outcomes matter.
Web delivery
If your old tooling cannot provide a great web experience, you need modernization. Traditional tech pubs tooling (Adobe, Madcap, Docbook) will struggle to develop wonderful, responsive websites that provide an amazing experience with documentation. There’s a natural struggle between artisanal hand-crafted documentation and producing tens of thousands of web pages that still offer a great experience despite the size of the site.
Continuous integration for documentation
When you treat docs like code, expect to enable more contributors, and when you enable more contributors, you need to automate builds and quality checks so your time is spent focused on doc outcomes, not running builds. Let the robots take care of builds and use tools that don’t require a seat license so that the writers aren’t having to build from their computers only. In OpenStack we can merge 50 changes a day in a single repository containing ten deliverables (web-delivered guides). We build draft copies with scripts for people to review the output online.
If traditional tech pubs tools product managers are reading, your next killer feature is Travis-ci job integration, Jenkins job enablement, and really any scripted way to build your output so that humans don’t have to click anything to build the docs.
Collaboration for documentation using code systems
Depending on your contributor base, you influence more people to respect the documentation and encourage contributors to improve the docs with you when the docs are in a code system. Across multiple repositories we deliver REST API documentation for almost 30 services. Some days there are over 100 changes that need to be reviewed for REST API docs.
Content management using code systems
I’ve presented and written about using code systems for documentation – git, GitHub, BitBucket, GitLab, and so on. See the resources section for a deep dive, but suffice it to say, I’m sold on using GitHub for your CMS and I know many other writers see it this way also.
Valid concerns
Here’s what you need to look out for and even embrace when the time comes:
Content sprawl: What goes where is a common question from contributors. Be ready with answers so your site doesn’t become a poor web experience. Have excellent navigation systems and way finders for readers.
Quality diminishing: Build a trusted set of reviewers and make sure they are equipped with a style guide and plenty of quality checks to keep in mind while reviewing. Be mindful and use metrics to ensure quality is a priority.
Loss of control: By enabling many contributors, you lose control of who writes what where. Be ready to trade control for many other benefits. I don’t have a control-based mindset so it’s natural for me to give up control in order to gain better outcomes.
Loss of choosing priorities: When you don’t personally manage and direct the teams of contributors, you don’t get to pick what is written first, second, or third. Or even if something is written at all. Have processes and systems in place for triaging doc issues, and create a culture where contributors have good judgement about what to work on first, second, and third.
Search and replace: When you need to make changes across multiple repositories and deliverables, be ready to up your bash scripting game or get help with it. Fortunately text manipulation is pretty powerful at the command line. Unfortunately some teams could be stuck with non-Linux-based systems and no tools to help with this problem.
Naming agreement: Unless you establish standards and have authority for naming certain parts of a project (plugin or plug-in as an example), you could waste time arguing about which name lands in the base.
Value diminishing: If you can’t train your writers to stop nitpicking grammar errors or capitalization consistency issues, and instead do technical reviews, you might have problems with a docs-like-code approach. In a docs-like-code world, be sure you know what is the most valuable contribution and make sure your teams can give those types of contributions.
In closing, you can see I’m a huge advocate for this approach to documentation. Please take a look at the resources I’ve been working on over the last few years to spread my enthusiasm and excitement for the modernization of technical documentation.