The four main documentation strategies explained
Clients frequently ask us for advice on how to approach their documentation workflows. These aren't really questions about the inner workings of Swimm's components, but are more along the lines of figuring out how to focus their writing efforts.
We suggest thinking of it more as a strategy than an absolute plan on who is going to write what, and when. There are four main themes that go into a documentation strategy.
- Firefighting
- Breadth-first
- Depth-first
- Task-oriented
Firefighting involves creating the level of documentation appropropriate for the area of the code as needed to answer questions as they arise.
Breadth-first means writing sparsely about as many things as possible. Brevity gives us a little bit of coverage essentially everywhere.
Depth-first means writing a lot about a single, or very few things. We'll have a small part of the code base documented extensively.
Task-oriented means a procedural tutorial to accomplish a specific thing. New developers will know what dependencies to install and how to run a build.
Most new codebases begin with a firefighting strategy coupled with some task-oriented guides to help new contributors set up and accomplish common things. Code that lacks documentation might benefit from a breadth-first pass and then firefighting as needed.
Customer-facing documentation generally requires a depth-first/breadth-second combo. But, whatever you do, it's likely going to be a combination of two or more of these.
You can read a more in-depth discussion of how these approaches go into an overall documentation strategy in our blog post about documentation strategies.. This is also available as a video presentation.