Documentation practice
at Canonical

We're working to establish patterns of excellence in documentation in Canonical, but not just for Canonical. The scale of operations at Canonical makes it an effective proving-ground for the models and ideas that we're developing — models and ideas that are being noticed and adopted more widely in the industry.

We actively seek new encounters with problems in documentation, in order that we may understand how our thinking can apply to them. We need to learn from experiences in other contexts.

We think, talk and write about the problems and practices of documentation, openly, and with whoever wants to take part part in that dialogue.

We regularly attend events where the topic of documentation is firmly on the table. Recent examples of participation include PyCon UK 2022, DjangoCon Europe 2022, Ubuntu Summit 2022, PyCon Namibia 2023.

Documentation is important for open-source software in several ways. One that's sometimes not properly understood is the value it has as a pathway into open-source participation and contribution.

In turn, open-source software also has a lot of significance for documentation. That's because it's one of the great entry-points into documentation practice. Most people in documentation are not trained technical writers, but the barriers to writing documentation in open-source contexts are low, and the context makes first, hesitant steps easier.

Open-source projects inevitably find it easier to secure top-class programming contributions than they do to attract the same level of expertise in documentation.

We engage with a number of open-source projects, providing guidance, support as well as material documentation contributions. Recent examples include Python and Django.

We eagerly absorb insight from others in the discipline. The challenges faced by practitioners in other organisations serve to illuminate our own, and we value the exchange of ideas and expertise they offer.

In particular, we've benefited from the experiences that others have had implementing Diátaxis at scale, or in very different contexts, as a means to refining our own understanding.

The scientific community faces a problem, that risks becoming a crisis, of reproducibility. Ever-more research relies on computation, and much of it is wholly dependent on it. Despite this fact, and despite the valiant effort of software research engineers, software practices in research in general fall very far behind the standards achieved in industry.

Documentation plays an important role in achieving and maintaining reproducibility. Members of our documentation team have held workshops dedicated to research software documentation, and explored the context in particular research institutions. Our Practice Lead for Documentation is a Fellow of the Software Sustainability Institute, running a long-term project to work with researchers, as much to understand the special problems faced in research as to share good practice that can be adopted.