Doc Writing Strategies for Engineers. Part Four: The DocCycle
In previous articles, you learned about InDoctrination and the DocAthon. Both of these are great ways to up your documentation game, but neither is really appropriate for long-term doc development.
To recap, InDoctrination brings your new people up to snuff and helps find big end-user issues. But you shouldn’t rely on final docs written wholly by newbies. The DocAthon enables you to pump lots of clarity and accuracy into your docs quickly. But it’s simply too labor intensive to use in the final days toward delivery. So how can you keep your docs moving in pace with your product? Use the DocCycle.
The DocCycle is a continuous sequence of finding and fixing doc user stories. In every sprint, your team works at least two high-value documentation user stories. It’s the best way to keep your documentation in line with your product progression. If you use the DocCycle, you’ll see your docs improve over time. And if you begin the DocCycle early, they’ll be in great shape as your deployment milestone approaches.
Note: Due to its synchronized nature, the DocCycle is really only appropriate when your team runs sprints. If you’re using Kanban, or some unrestricted workflow, the DocCycle will not likely be the best option.
How Does the DocCycle Work?
In my article about the DocAthon, I wrote about about chunking your docs — separating your documentation into content collections that an average person can consume in 2 hours (a chunk). This same technique is an important part of the DocCycle.
The second key concept in the DocCycle is randomness. Every sprint you assign a random chunk to a random team member. By using random assignments, you reduce the likelihood that one team member becomes the local doc expert on a particular feature. You also increase the chances that difficult and complex content is worked on as frequently as the low-hanging fruit.
Here’s an example: Suppose a team with four members — Shirley, Chad, Mercura, and Aristo — has a small doc set that they’ve divided up into four chunks. Let’s label them chunks A, B, C, and D.
The team is just getting started with the DocCycle, so the first sprint will have only one doc user story. It goes like this:
Sprint 5a: Shirley + Chunk C (review)
At the start of Sprint 5a, Shirley is randomly assigned chunk C. The user story says, “Review 5a.” So Shirley reads everything in chunk C. Shirley fixes 12 minor typos, and finds three more complicated issues that require user stories. Great! Shirley didn’t fix any of the major issues she found, because the task this sprint was just to find stuff. After going through the chunk, she marks the “Review 5a” user story complete, and goes on to her other Sprint 5a dev work.
Sprint 5b: Chad + Chunk A (review) and Mercura + Chunk C (fix)
In the next sprint, Sprint 5b, the team again randomly assigns a chunk (this time chunk A) to a random team member for review (Chad). Like Shirley did with chunk C in the previous sprint, Chad reviews chunk A, fixes eight typos, and creates one user story for a more involved bug. Chad then spends the rest of the sprint working on other stuff.
Also in Sprint 5b, the team selects a second random team member (Mercura). But instead of assigning Mercura to a new random chunk, Mercura is assigned to work on chunk C — the chunk that was reviewed during Sprint 5a by Shirley. Mercura acts on the user stories created by Shirley in the preceding sprint, fixing two, choosing to leave the third user story for the next cycle. Mercura spends the rest of the sprint working on other development user stories.
Sprint 6a: Aristo + Chunk B (review) and Chad + Chunk C (fix)
In the next sprint, 6a, the team will choose a random chunk (B), a random chunk reviewer (Aristo), and a random team member (Chad again) to work on the user stories Mercura created against chunk C. And so the cycle continues.
Ideally, your team continues this process without pause as long as you have a product to support.
When to Use the DocCycle (and When Not To)
You might think that using the DocCycle is a no brainer, especially for teams that are already using sprints to manage workflow. The truth is, though, there are a few conditions.
If your docs are stale, and the amount of work needed to get them usable is a project all by itself, and you have a reasonable amount of time, the DocCycle is definitely a way to go. Ditto if you are starting work on a brand-new product or feature. Using the DocCycle, you develop your docs along with your product. As feature freeze approaches, your docs are much closer to being ready than otherwise.
Because of the gradual improvement that the DocCycle provides, you wouldn’t want to use it if you had a large amount of work that had to be done quickly. For example, if you’d put off documentation until the final sprint before deployment, the DocCycle wouldn’t help you. In that case, the DocAthon is a much better option.
Further, if your core product is mature and doesn’t change very frequently, using the DocCycle might be overkill. You can have an occasional InDoctrination to handle content tweaks and fine-tune the clarity.
The Critical Link: Your Team Commitment
This is all fine and dandy on paper, but the whole scheme collapses like a house of cards if your team doesn’t commit to the spirit of the workflow. Deprioritizing or not assigning the doc user stories, doing half-hearted reviews, or even skipping the review cycle turns the DocCycle into the Cycle of Doom. After just three or four sprints it won’t be working for you, so you’ll just stop doing it. Your scrum driver needs to be diligent in helping to push, prioritize, and assign the doc user stories every single sprint — even if your current doc backlog is nil.
Pluses and Minuses
Nothing beats the DocCycle in helping you attain the most accurate, clearest documentation possible without the help of a tech writer — as long as you follow through on the user stories. If you just fix the easy stuff, and let the doc user stories languish without action, you end up with a backlog graveyard. If you take on the DocCycle, you need to be vigilant and follow through.
In my next and final article on Doc Writing Strategies for Engineers, I compare the three strategies you learned, and give you a few more tips to get you on your way to better docs.
