Engineering transformation through documentation

To help bring our ambitious documentation plans to fruition, we’re going to be hiring people to work in documentation – over the next couple of years, we’ll be increasing the number of Technical Authors at Canonical four-fold.

This isn’t about documentation alone. If documentation is part of a product, and documentation work is part of engineering, then it has implications for engineering too.

---

Generally speaking, technical writing is a poorly-understood discipline in the software industry. It’s a specialised role, and though the skills that it requires are typically exercised privately, the results are very public.

And yet, everybody seems to have confident opinions about documentation! For example, an engineer might bristle hotly with indignation if an outsider were to cast judgements or make pronouncements about software theory or practice – but not hesitate to do the same about technical documentation.

Some of this is fair enough, and some of it must change. 

Documentation in software engineering

Product documentation is public property. Like software, it exists to serve its users. And, as in the case of software, the final test of documentation is: does it meet the needs of its users? So it’s perfectly right that everyone is positively encouraged to think about, and express opinions on documentation; it’s part of public ownership of it.

On the other hand, it’s problematic that in the software industry, documentation is not properly understood as a technical discipline. In many instances, it’s not even understood that it is a technical discipline, that takes time to learn and longer to master, and that there are right and wrong ways of doing things, that themselves might not be obvious, and so on. This gap of understanding is one of the reasons that so much software documentation is not as good as it should be.

Professionals who work in the discipline of software have a strong tradition of looking inwards, at their work and the way they do it. Programming is a reflective craft, with effective values of self-criticism. For programming, software engineering has paradigms, methodologies, models and movements, that are in continual evolution and dialogue with each other. For documentation – we cannot say the same.

Thinking about documentation

Documentation is part of software engineering, but much less thought is given to it. Questions like how should we do it? what are our values? what works? how can we advance the discipline? are asked often of programming, and rarely of documentation.

Sometimes in software, we’re so far from treating documentation as a practice deserving attention that the mere existence of documentation can be considered an achievement. This is extraordinary. There can be no other industry in which the standards of product documentation are routinely set so low.

What we’re going to do about it

The clearest way to signal our intention to change this pattern is by hiring and dedicating people to work on documentation, not just as technical writers who produce it, but to be Technical Authors: visible, high-profile practitioners of the discipline with an important role in defining our engineering culture.

Our plan, for the next few months, is to increase the number of Technical Authors dramatically, from six full-time authors at present, to at least 28. That’s an enormous increase. The sheer number of new colleagues who are dedicated to documentation will make a difference, but it’s not all; what also matters is the role that our Technical Authors have.

What Technical Authors do

Canonical Technical Authors are key members of engineering teams. These teams work on a vast range of software engineering challenges and products. The products and their documentation need to meet the needs of an equally wide range of users: from end-users of Ubuntu on the desktop to kernel-level engineering teams across multiple different industries, and everything in between.

Documentation has to be like security, or performance: a team responsibility. It can only be done effectively when it belongs to everyone in the team, and is led effectively. A Technical Author leads the team’s documentation efforts.

At Canonical, Technical Authors are not passive communicators of knowledge. They are active contributors to the business of software development; their contributions are real, meaningful and respected.

Above all, they have technical authority, hence their title. They are custodians of one of the most important relationships in software, the one between a product and the users’ grasp of it.

Authors are inventive and creative. Their work helps define the identity and presentation of products. They identify the needs of users, and frame products and their operation according to the needs of those users. They find imaginative ways to present highly-technical ideas and structures in narratives and flows that lead users to understanding and success. They find new and better ways to teach, show, describe and explain.

Technical authors engage critically with their developer colleagues – many technical authors themselves have engineering backgrounds – to challenge and question assumptions about the way products work and are used.  They dive deeply into the thinking behind software decisions, and use their skills of comprehension and communication to hold up a mirror that reflects them back, and brings them into focus. They are able to show how a problem in communicating about a technical matter can represent a problem in the technical concern itself.

They listen. Listening is an active discipline of receptivity to needs. It’s a crucial part of the role, because users of software are not always inside formal feedback loops, are sometimes hard to hear, and always have needs that must be placed at the heart of our documentation.

It’s a special constellation of abilities and responsibilities – hard to find, and hard to do well – and one that the software industry needs to understand better.

---

(Does this description of the role of a Technical Author appeal to you? Perhaps you’re ready to be one of them. Learn more – see our job description for Canonical Technical Authors.)

Transformation engineering

By introducing new Technical Authors into teams right across the company, we are purposefully and systematically engineering a tectonic shift in our own software culture. It will take place through our documentation practice and the professionals who lead it, our Technical Authors.

A Technical Author is a transformative presence in an engineering team. They will change the way that Canonical does documentation, but will also change the way Canonical makes software too.

We expect the presence of the new Technical Authors to have an immediate impact in each team, and a permanent effect on Canonical engineering. It will place new conversations, perspectives and ways of thinking about making software right at the heart of the engineering process.

This is also an opportunity for talented documentation authors who are looking for a new challenge. If your skills and interests lie in the intersection of technical writing, software product documentation and open-source software development, we’d love to hear from you.

Technical Author roles at Canonical