Your submission was sent successfully! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates from Canonical and upcoming events where you can meet our team.Close

Thank you for contacting our team. We will be in touch shortly.Close

  1. Blog
  2. Article

Nathan Hart
on 29 June 2022

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.

Related posts

Graham Morrison
26 February 2024

Introducing Canonical’s Open Documentation Academy

Community Article

tldr; Our Open Documentation Academy starts this week with our first weekly Documentation Office Hours on Friday 1st March 2024 at 16:00 UTC. Everyone is welcome! Keep reading, or see our forum post for more details and to leave questions. Many of us at Canonical wouldn’t be here if it wasn’t for Linux and open ...

Nathan Hart
15 August 2023

Docker on Mac – a lightweight option with Multipass

Ubuntu Article

For those looking for a streamlined, lightweight command line interface for Docker on Mac, look no further. Multipass is a flexible tool that makes it easy to create and run Ubuntu VMs on any platform, and it comes with built-in tools that make running applications like Docker feel native on platforms such as macOS. What ...

Jeremie Deray
5 May 2023

ROS development on Linux, Windows and macOS

Robotics Article

Historically ROS has been developed on top of Ubuntu, relying on the distribution as a stable base providing tools (like GCC, CMake, Python to name a few) and libraries (such as Boost, Eigen, PCL) and following its release cycle (a distribution per year, an LTS every two years). This synergy has worked great for more ...