Documenting Recurring Processes
The two-pronged approach we use to document recurring processes internally.
Tasks that you have to do once every three to twelve months are the worst.
The time between tasks is short enough to be considered "recurring," but too long for you to get comfortable with the process. If it involves more than two steps, you have trouble remembering exactly how you did it the last time. It's easy to forget all the little details that go into accomplishing the task.
These are the most important processes to document.
Our Approach
We follow a two-pronged approach to documenting these types of processes:
- Maintain a wiki with step-by-step instructions for completing the task
- Document each recurrence of the task with screenshots in FogBugz (our bug-tracking database)
This approach allows us to maximize the signal-to-noise ratio within our wiki, while still retaining detailed information for future reference in FogBugz.
The Wiki (DokuWiki)
We use DokuWiki to document the steps for each process.
The wiki represents the general solution. It is the primary source of documentation we rely on when executing the task. It is heavy on text and light on screenshots.
The wiki is a living document that gets tweaked every time we execute the process.
The Bug Database (FogBugz)
We use FogBugz to record occurrence-specific notes.
Each occurrence of the task gets its own case. We refer to the wiki instructions as we work through the process, but any screenshots we capture along the way get saved to the FogBugz case. In this way, the FogBugz case is treated like a manual log file.
Much like an automated log file, the contents rarely get a second thought.
However, like any log file, it can provide crucial information when troubleshooting problems. Oftentimes, decisions we make at the beginning of the process lead to issues later on. Having these early details, including screenshots, is often the difference between figuring out what went wrong and being hopelessly confused.
And if we can't figure out what went wrong, we have no way to fix it for the next time.
The Reason Screenshots Go in FogBugz and Not DokuWiki
One problem with screenshots is that they are almost instantly stale.
Screenshots often include temporal data–such as a mailing date–that only applies to a single instance of a task. By relying on text instead of screenshots for the general solution, we gain flexibility. For example, instead of a screenshot that shows a mailing date of 2021-03-01, we can include a wiki instruction like:
- Enter a mailing date of March 1 of the current year
The screenshotted date of 2021-03-01 has value...when documenting the execution of the process in 2021. That's why we take the screenshot and upload it to the 2021 FogBugz case for the process.
In future years, having the 2021-03-01 date visible in a wiki screenshot could generate more confusion than it relieves.
Integrating DokuWiki and FogBugz
We maintain a two-way integration between DokuWiki and FogBugz.
At the top of our wiki instructions, we include links to past occurrences of the process. Here's an example from our annual bill creation process, which we discuss in further detail below:
Within FogBugz, we created a custom field named "Wiki" where we can enter the URL to the relevant wiki page that holds the step-by-step instructions. The URL is a clickable hyperlink, so it makes it easy to jump back and forth between the wiki and the FogBugz case:
Using this approach, it is very easy to jump back and forth between the step-by-step wiki instructions that apply to the process generally and the screenshot-heavy "log" of each recurrence of the process in FogBugz.
Documenting Edge Cases
Another benefit is that we can provide detailed documentation on handling edge cases without cluttering the main wiki article.
The way we do that is to insert links to specific portions of the relevant FogBugz case whenever we come across a situation we haven't seen before or that has caused problems. Here's an example from step 13 in one of our documented processes:
And here is Case 4044 referenced above:
Back in 2016, we received tax collector data in a different format than it had been provided in the past. We didn't catch the change until after we had distributed the data files to our tax collector customers. We opened Case 4044 in FogBugz to track resolution of the problem.
After we resolved the problem, we updated the wiki instructions with a link to FogBugz to avoid the bug reappearing in the future.
