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 technical authors to join multiple engineering teams, working on products across Canonical's portfolio.
Our work identifies four pillars that support documentation success:
Where we want to go — the standards and quality we seek, so that documentation meets its users' needs.
Our attitude towards documentation, and a culture of documentation discipline that makes it a living concern.
How we do our work, so that we consistently produce better output with less effort and more satisfaction.
The tools and machinery we adopt to write, maintain and publish documentation, that serve our work best.