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…