Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.
Delivering High-velocity Docs That Keep Pace With Rapid Release Cycles
Docs or It Didn’t Happen
Requiring docs within releases. The standard is now that we must ship with docs on time. We must have them. It is not an option to not have them.
Unfortunately, this didn’t match Rachel’s reality. Pantheon, her employer, puts humans at the top of the stack and that is critical, but, they didn’t have the automation and background processes. Unfortunately good intentions don’t create docs. Content became stale because they were chasing features.
Her first thought was that we should enforce docs as a standard component. Collectively we should agree docs are a blocker. This, however, turns out to be a pie-in-the sky goal that is not realistic. This is often a huge reality check for people.
Docs are not going to block a release until trust in delivery is established.
Failing to deliver docs is a symptom of the broken process in the docs team, not the software. There is a misalignment in how docs are made and software is developed. Once she realized that her workflow and the process inside of the docs team was the failure point, she tried to figure out why. The product was agile and docs were not. The docs team couldn’t catch up until they could keep up with the development pace.
The development pace was set based on how releasing software should be easy. The principal of continuous delivery.
Docs must meet the same standards of reliability and repeatability that engineering uses before docs can be enforced as part of the release cycle.
Creating a Plan
- Increase Project Visibility
- Simplify Peer Reviews
- Automate Grunt Work
Increase Project Visibility
They created a centralized workflow to track issues and progress. They decoupled linear processes to keep one unit of work from blocking other work. They went open source for both visibility and public comments/contributions. This had a side effect of creating a whole slew of beta testers who would test the PRs.
They also added a system of dependable notifications. Integrating GitHub into other communication tools, like Slack. These notifications are not suggested for integration into your main communication channel. A bot dedicated channel is generally better to prevent it from overwhelming everyone.
Simplify Peer Reviews
The ability to get a +1 from an SME as quickly as possible was the priority. Therefore they focused on the path most followed. There old process was very disruptive and required a lot of work. They instead created notifications and linkages that allowed reviews to be done with a single click.
To do this they rely on in place editing inside of GitHub. They don’t have SME comments, instead they do actual edits that trigger a PR.
Automate Grunt Work
Automation can easily handle things like checking links, moving files, etc. Redundant tasks are a waste of time. This resulted in the:
- ability to stage content in isolated environments with automated generated public urls
- deployment to production with a single click
- automatically performing link checking, etc.
An comment is automatically put in a PR with the location of the latest staged version of the PR via the CI/CD system. It runs HTML validation, and other tests. They are using CircleCI and are using it to restrict the ability to merge if something isn’t right.
Are we done yet?
CI for docs isn’t the end of the road, however it is an essential tool for building trust. Ultimately, for docs to become an enforced requirement of the release cycle, you need buy in from everyone.