The future of documentation at Canonical

Our software documentation is part of how we talk to each other – our users, our colleagues, our community. It’s a way we demonstrate how we value each other – including how we value you. 

We’ve understood the importance of this for some time, but actually finding a way to express those values in our practice is less easy.

One thing that has made it difficult at Canonical is the complexity of our engineering, product and services portfolio. Our software spans a range from single-purpose command-line tools to vertical ecosystems composed of dozens of discrete component products, created by dozens of independent engineering and product teams.

We’ve been able to create unified and coherent software product lines, but we’ve been less successful doing the same for documentation. We want to do better for our documentation users – this is how we’re going to do it.

A documentation transformation project

We know that merely valuing documentation is not enough to take us where we want to go. Even producing better documentation isn’t enough. We need to create and maintain software documentation, deliberately and systematically. We need to do it according to a plan that will give us the unity and coherence we seek, and will sustain it into the future.

So that’s what we are doing. We have embarked on a comprehensive, long-term project to transform documentation. Our aim is to create and maintain technical documentation and documentation practice that will represent a standard of excellence in the industry. We want it to be the best it possibly can be.

By “best” we mean documentation that above all else understands, respects, reflects and serves its users’ needs. These are the values that we stand for, that we will express in our work. They are values that we want to become known for.

This is a permanent, on-going commitment. It’s work that will never end. It has already started, and will become part of the fundamental Canonical discipline of making software. We hope that the standards, discipline and values we assert this way will spill out from Canonical, into our wider community, and will make a difference to our industry as a whole.

This project will change the way that nearly everyone who works at Canonical thinks and talks about and approaches documentation. It’s going to affect the work of teams and individuals right across the company.

Our transformation project will take place across four distinct concerns in documentation. To succeed, we will need to do the right thing in each of them.

Direction, care, execution, equipment

These four are direction, care, execution and equipment. They are four things that you need in order to succeed in any endeavour – not just in documentation, but they apply here too just as firmly.

Direction – knowing where to go with our documentation

Direction represents the standards and quality of our documentation. 

Direction is where we’re going. It’s not a final, fixed destination, because there isn’t one. The landscape itself is going to change while we’re getting there. But we still need to understand where we are and know whether we’re going in the right direction. We need to be able to tell the difference between documentation that’s done right and documentation that is not.

The Diátaxis documentation framework is our map and our compass for this endeavour. It’s a widely-adopted system that places the user, and the user’s needs, at the heart of thinking about documentation.

The framework solves some key problems in documentation, but it will be just part of a wider approach to documentation in which the user’s needs are placed centre-stage.

Care – our attitude to documentation

Care is the attitude and discipline that we bring to the activity of documentation.

Care turns willingness into sustained and successful practice; it’s the guarantee that things will get done. It doesn’t mean that a few individuals care, however fiercely and passionately; it’s something that must be expressed by the whole culture of the organisation, becoming embedded into its ways of working and thinking.

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.

Like engineering, documentation is a discipline. It’s less well understood or talked about than that of engineering, but our aim is to develop and formalise it as a discipline, not just for our own benefit, but to contribute to the advancement of software documentation in general.

Execution – how we do our documentation

Execution is the way we actually do what we’re doing.

Well-executed work produces better things, and the work itself is better too. The work of a skilled craftsperson is more efficient, less effortful, smoother, quieter, less tiring, more enjoyable to perform, more pleasurable to observe.

Documentation is a craft, but it’s one that has been neglected in our industry, and has suffered as a result. All too often, authoring practices and approaches in documentation are modelled on ones which don’t transfer well. The experience for teams and individuals is correspondingly unsatisfactory: they work harder, for poorer outcomes. Good intentions rarely survive the realities of negative experience. They certainly cannot develop into flourishing, positive cultures if the very ways people work turns out to be a brake on their progress.

At Canonical, we’ll be adopting and developing approaches to avoid these pitfalls, that recognise the distinct nature and needs of documentation, and particularly the fact that documentation – unlike engineering – is about something other than itself, and tracks a permanently moving target. 

Our approach begins with the idea of documentation as an activity, one that makes progress through iterative, evolutionary processes, on a model of organic well-formed growth. Our aim is to make documentation practice a constant series of small, easy, low-stress steps, an ordinary and unremarkable activity that fits comfortably into our work on software, and quietly produces remarkable results.

Equipment – the documentation tools we use

Equipment is the last of these four pillars of endeavour, the tools and machinery we adopt to do our work.

Each of the others represents value in itself, but equipment is only a means to an end. It’s tempting – especially when working in a technical environment – to be bewitched by technology and its promises and haunted by its limitations. In truth, as in any craft, tools are at best an enabling factor, at worst a limiting factor. Tools exist only to serve work.

Our documentation authors, like craftspeople in other disciplines, will do their best work when the tools in their hands cease to be an everyday concern, so that they can focus on their work, and not on the tools themselves. Humble trial-and-error and the modest reports of everyday experience will guide us more reliably in our choices than daring ideas and elevated principles.

Once the question of technology has been deromanticised, it’s easier to select tools pragmatically, knowing that it’s very unlikely any particular choice will be a make-or-break decision, and understanding that since technology itself never stands still, we should expect to have to revisit our choices in due course anyway. In the meantime, we’re assessing our options to find out where and how we can do the right thing for the creators and users of our documentation. Our work here starts with the questions: what does our work need, and what can we find that will serve it best? 

What it will mean to succeed

Our success will lie in getting all four of these right. The importance of success is recognised throughout Canonical: we will not be the software company we want to be, unless we can achieve the excellence we seek in our documentation.

We believe we know what we need to do now, so that our intentions shall become endeavours and our endeavours shall bear fruit. We hope that in time the fruits of our efforts will be enjoyed by as many as possible – not just by our users and customers, but by other organisations in our industry too, and by the people they serve.

If documentation really is part of how we talk to each other, then that includes listening. We’ll know when we’re getting things right because we’ll hear it. We’ll hear the conversations we have shift to a deeper level of understanding as we progress. And all the time, we’ll need to keep listening to ensure that we are meeting our users’ needs.

When we talk to you through our documentation, we want you to find us responding more deeply and confidently to those needs. We invite you to judge the value we put on the conversation, and on you, by the way we conduct our part in it.