close
esc

Request a Demo

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

How Canonical Systematically Improves Developer Documentation

Daniele Procida

Interviewer: Abi Noda

We frequently see “documentation” as a top problem customers want to improve. It’s a familiar problem for many teams: documentation can easily 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 exactly they’re doing to improve their documentation process so we can distill their approaches for others to learn from. 

For this post, we interviewed Daniele Procida, Director of Engineering at Canonical. Daniele has an extensive background with establishing documentation systems, having contributed to both Divio and Django’s documentation as well as speaking at various conferences about 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 with the aim of creating 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 having to work harder, he does think 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 five considerations Daniele recommends 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 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 knowledge and skills that have been 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; introduction to 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

Tracking documentation objectives

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 deromanticize 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.

Daniele Procida

Daniele Procida