Doc Writing Strategies for Engineers. Part Three: The DocAthon
Dogpiling. Ruck. All hands on deck. Barn raising. Team push. Scrumble in the City. There are a lot of words and phrases that mean “all of us have to pitch in together right now or it’ll never get done.” For documentation, it’s a word, and that word is DocAthon.
The DocAthon is an event where your entire team — and maybe some non-team members as well — spend an entire day working exclusively on your docs. It’s a grand literary party, where everyone has a single objective: better docs. In this unit, I take a look at how to organize, run, and recover from a DocAthon.
Who Do You Need?
Everybody on your team. The single most important element of the DocAthon is people. Choose who must and who may be in your session with care. Generally, you want:
- Your veteran team members, as they have the widest view of what your product is about, and they’ve more than likely had some interaction with your users. These people tend to focus on accuracy.
- Testers and operations folks, if they are not on your core team. These people often lean toward completeness.
- Product champions and early adopters. They lead the fight against staleness and contradictions.
To this group you can add:
- Scrum leaders, stakeholders, product owners, TPMs, and other team drivers. They may focus on content with a view to the history of your team and product.
- New team members who don’t know much about your product yet. These are your fresh eyes. They take the part of novice end users.
- Anybody who wants to pitch in. These folks will be all over the map.
Different people contribute in different ways, so it’s great to have diverse viewpoints during a DocAthon.
What Should You Check?
It depends. If this is your first DocAthon, include everything: doc comments in code files, user docs, white papers, slides, any kind of doc on any platform. Later, after your team gets a feel for the relative quality of your docs, you can choose a specific chunk to work on. That’s right: chunk. A doc chunk is just a subset of your docs that may or may not be compose of related parts, but which can be read through by most people in 2 hours.
It’s these chunks you will assign to people during the DocAthon. Depending on how your product and its docs develop over time, your chunk compositions may change. Still, chunks help keep people from stepping on each other’s work. Plus, if you give chunks identifiers or tags, you provide a way to group user stories that you create during the DocAthon.
When to Run a DocAthon
How do you know when it’s the right time to put together a DocAthon?
Most of your core team is present. In fact, most of the DocAthon participants need to be veteran team members, as these are the people who can see the most facets of your docs — team history, product history, roadmap, intended users, and so on. You want many people with this insight, because they have the broadest possible view.
Your product is at least Beta. Don’t bother throwing a ton of labor at your documentation if you haven’t gotten to Beta yet. If you’re still figuring out what your product will do, coordinated doc work by the whole team has less value.
Note: You should still provide alpha docs to early adopters for feedback.
You need to get a significant portion of your docs up to speed quickly. Or you need to really learn the true state of your documentation. Things fly fast and furious during a DocAthon. However, it’s not the technique you want to use if you want to fine tune your documentation — use the DocCycle for that (I’ll be writing about the DocCycle soon).
Remember that you don’t need to focus on your entire documentation set via your DocAthon. You can target just a couple of chunks, or a segment of your backlog — anything that needs a fast, coordinated effort by multiple people. And be sure to schedule the DocAthon far enough in the future to guarantee that people can participate. Don’t hold it on a Friday, since the DocAthon retro needs to be the following calendar day. (More on the retro coming up.)
How to Run a DocAthon
Process, process, process. It’s everywhere. Unsurprisingly, it’s in how you run a DocAthon as well. But you have room to fine-tune it specifically for your group. If this is your first DocAthon, here is a starting process.
1. Chunkify your documentation. You may want to create product tags for the chunks and topics for the specific DocAthon.
2. Assemble your team. Collect everyone who can provide value. While most people should be product veterans, technical diversity is important. People who know a lot about your product will likely concentrate on clarity and accuracy. Everyone else will focus on usability, identify gaping content omissions (stuff you assume everybody already knows), and information the first group ignores (stuff you assume isn’t important enough to fix).
3. Establish a few working rules. Don’t be draconian here, but at minimum:
- It’s time for doc work only. People need to get into the Doc zone, which won’t happen if they are multitasking.
- Participants must commit to a time span. Ideally commit a full work day. You adjust this for spanning time zones and if you are concentrating on only a portion of your documentation.
- There are guidelines for what to fix and what to bug. People should be encouraged to fix whatever they want to fix, but there may be issues you want people to ignore. Decide if you want one user story per fix, one per chunk, or none. Every found and unfixed issue needs a user story — here’s where your chunk tags come in.
- There will be checkpoints. Settle on a reasonable checkpoint interval. You want to stop every 60–90 minutes to see how people are doing and to identify any common trends. You may find issues that can be fixed through automation. People may be handling the same things differently in different chunks.
- There are guidelines for handling disputes. People are fixing content, and they may have different opinions on how to fix things. If a dispute on how to fix something lasts more than a few minutes, postpone the fix, create a user story, and schedule a meeting after the retro to work it out.
4. Plan a retrospective for the next calendar day. During the retro meeting go over these things:
- How people felt about the DocAthon experience
- How people feel about the state of the docs
- What people think is the best next step for the docs
- What the new backlog looks like
- Every user story must have an Assigned To and a Priority
Finally, with docs in better shape, a nice backlog of assigned and prioritized user stories, and a team awash in happy doc thoughts, you can schedule the next DocAthon a few months out and soldier on!
The DocAthon is a great way to get all your team invested in all your docs. Used periodically, it can help keep your docs up to snuff. While it rarely provides the fresh-eyes perspective of InDoctrination, it is a strategy that you can use over and over to maintain your docs.
In my next article, I’ll take a look at a way to integrate your doc work with your product work, enabling your customers to benefit from the most accurate docs possible: the DocCycle.
