Documentation practice at Canonical
At Canonical, we have embarked on a comprehensive, long-term project to transform documentation. Our aim is to create and maintain documentation product and practice that will represent a standard of excellence. We want documentation to be the best it possibly can be.
For too long in our industry, documentation has been allowed to be a secondary aspect of software development. Our approach will make documentation a core engineering concern, governed by systematic principles and requiring conscious practice, whose values inform the work not just of technical authors, but of all our engineering and product teams.
Documentation as practice
A central principle we hold is that documentation is an engineering practice, rather than an engineering task.
At Canonical, engineers and product managers make real and substantial contributions to documentation, as part of their everyday work. Documentation is not a siloed activity, it's a responsibility shared by everyone who works in engineering, product or support.
Everyone is expected to think and care about documentation, specialists and non-specialists alike, in just the same way that quality and security are shared concerns. If you're applying to Canonical for an engineering role, don't be surprised to be asked about your work in — or your thoughts on — documentation at a job interview.
Documentation with rigour
It's a key part of our project in documentation to understand and define documentation as a rigorous discipline in software engineering, one with rules that apply generally, are derived from sound principles, and are tested in action.
Documentation in software deserves — but has never enjoyed — a scientific approach. We need our ideas and models to be examined and challenged, not just by us and our colleagues, but beyond Canonical too. Our models are working models, not the last word on the subject.
Documentation practitioners at Canonical are not just in the business of producing documentation — not even just the business of producing excellent documentation. They have a responsibility to advance the state of the art of documentation, and to advance documentation practice itself.
We work together towards this end, to define the practice of documentation. Our approach is critical, exploratory, collaborative and iterative.
We're hiring
We're hiring technical authors to join multiple engineering teams, working on products across Canonical's portfolio.
Four pillars
Our work identifies four pillars that support documentation success:
Direction
Where we want to go — the standards and quality we seek, so that documentation meets its users' needs.
Care
Our attitude towards documentation, and a culture of documentation discipline that makes it a living concern.
Execution
How we do our work, so that we consistently produce better output with less effort and more satisfaction.
Equipment
The tools and machinery we adopt to write, maintain and publish documentation, that serve our work best.
Read about our plan to put these pillars into place at Canonical ›
Read more
Diátaxis Framework
Read more about the Diátaxis authoring framework
Documentation articles
Read our documentation articles on the Ubuntu blog
Careers at Canonical
Take a look at our open roles here at Canonical