Multipass documentation: proudly a work in progress

In February of this year the Multipass team took on a challenge: completely overhauling our documentation. Canonical has put a renewed emphasis on documentation in recent months, led by Daniele Procida and his Diataxis framework, and we wanted to be an early adopter of this methodology. We had no idea where to start, but fortunately we had some help. The Juju team kindly agreed to part with their technical author, Teodora, for five hours a week so she could help us with this transformation.

Teodora’s help was the pilot of a new program spearheaded by Daniele, the documentation secondment program. The program ran for just twelve weeks, for which we had some ambitious goals. We wanted to restructure our documentation to align with the Diataxis framework, and to produce a high-quality, end-to-end tutorial for Multipass. In the course of striving for these goals, we learned a lot.

Lesson one: breaking the ice

Existing documentation acquires a certain sheen with time. It begins to seem more like it’s written in stone than text in a discourse post. It can feel really hard to make a change to something that has been working for so long. Teodora broke that spell for us on day one. After discussing our goals for the secondment, the first thing we did was start making changes to the documentation together as a group. At first, it felt scary. What if this wasn’t right? Maybe there were several changes that had to happen all at once, what if we left a thread hanging? We learned early in this secondment that all of that is ok. The documentation will never be “done”, so our goal is simply to make progress. In fact, making a change that necessitated subsequent changes was just more motivation for the team. Daniele calls this “building towards a crisis”.

Lesson two: perspective and a critical eye

Documentation is critical to users of a product and the community, but it’s hard to write documentation for them. As people who are deeply involved in the product daily, it’s hard to break out of our frame of reference and take on the many other perspectives that will be reading our documentation. Our docs need to be written for first-time users, seasoned pros, and everyone in between. We reviewed many docs together as a team to hear Teodora’s take on them (it helped that she was new to Multipass at the time!), and over time we learned to better see the docs through the eyes of non-experts. By the end, we had all developed a critical eye for documentation, and we’re much better now at knowing what needs to change to continue improving our docs.

Lesson three: structure and storyline

Not only do docs need to be understandable for readers of all backgrounds, they need to be more than the sum of their parts. This starts with the Diataxis framework, but it doesn’t end there. Docs need to take a reader in, understand why they’re there, and guide them on their journey, suggesting new paths to explore and giving relevant information as needed, not all at once. Some might suggest that well-written code can be its own documentation, but I think this is misguided. Yes, documentation may contain redundancies. Yes, it’s a difficult task to keep it up to date. But people understand stories better than code. They want to be guided, taken along for the journey. Documentation that can accomplish this can be the cornerstone of a thriving open-source community.

Parting thoughts

While we know our docs will never be complete, it does feel like we’ve hit a milestone on this journey. We’ve learned so much as a team, and made so much progress together with Teodora that it feels worth celebrating. The secondment gave us the tools and good habits we need to keep making gradual improvements, continually. We’ve learned that consistency is the key to success in building documentation.