How Canonical systematically improves developer documentation

We frequently see “documentation” as a top problem customers want to improve. It’s a familiar problem for many teams: developer documentation can quickly become outdated or disorganized. Sometimes, the issue is that the documentation is poorly written; other times, there are specific areas that are under-documented. We’ve started interviewing leaders to understand what they’re doing to improve their technical documentation process so we can distill their approaches for others to learn from. 

In this post, we’re excited to share the insights of Daniele Procida, Director of Engineering at Canonical. Daniele has an extensive background in establishing documentation systems, including contributing to both Divio and Django’s documentation and speaking at various conferences on this topic. (See his talks “What nobody tells you about documentation” and “Always complete, never finished”.) 

Upon joining Canonical, Daniele was tasked with transforming their documentation to create a technical documentation practice that represents a standard of excellence in the industry. That means Daniele has spent a lot of time thinking about this problem—but when we asked if other teams could reasonably apply his strategy, he said, “Most teams don’t need to ‘work harder’ at documentation; they just need to do it in the right way.” 

Note: while Daniele recommends “making documentation easier” instead of working harder, he thinks that organizations would benefit from having someone who is the custodian of documentation quality and standards. He says, “Whether that’s someone’s duty or whether it’s a full-time role depends on scale, but the important thing is to have a unity of vision that’s kept active and alive.”

Here are Daniele’s five key recommendations for making documentation easier.

1. Introduce standards that define what “good” looks like

Daniele’s Diátaxis framework offers a set of standards that meets a matrix of user needs by distinguishing four distinct types of documentation:

1. Tutorials: What you decide a beginner needs to know
2. How-to guides: An answer to a question that only a user with some experience could even formulate
3. Reference guides: Technical descriptions of what something is and how to use it
4. Explanations: Discussions that clarify or illuminate a particular topic

Note: Here’s a slightly different breakdown of the types of documentation from Niklas Begley at Doctave. 

Daniele points to “not knowing where to go” — for documentation authors as well as users — as a common cause of a failed documentation system. Therefore, documentation standards should specify where to go to find or contribute to different types of documentation.

2. Teach good documentation practices during onboarding

‍An interesting tactic Daniele shared: Running a 4-hour workshop once a quarter with new hires. Daniele’s session is focused on training developers about the types of documentation, where each should go, and what good documentation looks like. This helps instill a culture of good documentation from the beginning of each developer’s journey with the company. 

Only a small part of the workshop is a presentation; most of the time is spent doing exercises that reveal to developers the right way to write different types of docs. In the end there’s a certification that acknowledges the skills and knowledge learned. 

Here’s a summary of Daniele’s workshop agenda: 

Outline:1. Part 1 - Quality: understanding how documentation works and what good documentation looks like; introducing the Diátaxis documentation framework*;* applying it to documentation problems; applying it to your work.

2. Part 2 - Execution: getting things done; authoring practices and approaches; getting work started and keeping it going; making life easy for yourself.

Transforming a culture is hard and delicate work that’s all too easy to disrupt. It’s a long task of nurture and education that requires finding ways to bring teams and individuals along, willingly, with the desired change. Still, it’s more sustainable than trying to do the right things in an adverse culture. On the contrary, to establish a good culture is to set virtuous cycles in motion, in which doing the right thing becomes the easy thing to do, and in which practice reinforces values.

3. Partner with teams to set quarterly objectives for improving documentation

‍Daniele partners with teams to set quarterly objectives around areas of documentation to improve. He uses a spreadsheet to track all teams’ objectives and progress so that the results of everyone’s efforts can be clearly tracked.

Here’s an (edited) example of Daniele’s tracking sheet: 

A good culture of documentation is the hardest thing to attain. Everything else depends upon it; in its absence, no amount of effort or wisdom will be sufficient. Canonical’s stated ambition to set standards of excellence in documentation helps define values that inform all our work. 

4. Be careful not to force too much structure

Creating good documentation requires skill and hard work; there’s no need to make it harder still by working in inappropriate ways. Documentation is always tracking a target — the software it refers to — and sometimes that target moves swiftly. Documentation work needs to be nimble and lightweight.

Planning in documentation is often unhelpful. Processes that work well for, say, software development are not always suited to documentation. Instead, adopting a model of organic, iterative improvement can reduce documentation-related anxiety and effort, and allow teams to accomplish useful work faster.

5. Make flexible tooling choices

“Tools exist only to serve the work.” Daniele aims to de-romanticize technology decisions, “understanding that since technology itself never stands still, we should expect to have to revisit our choices in due course anyway.”

His personal preference for tooling: Sphinx for publishing, reStructuredText for markup, Git for version control, ReadtheDocs.org for hosting. But, again, he encourages teams to find something that works best for them.