Documentation, development and design for technical authors

Typically, a technical writer takes the product created by a development team, and writes the documentation that expresses the product to its users. At Canonical we take a different approach. Documentation is part of the product. It’s the responsibility of the whole team. Documentation work is led by a technical author, who is part of the team, and whose title signals their technical authority.

In documentation, the work of articulating internal logic, interfaces, workflows and conceptual relationships can expose product design problems and reflect them back forcefully to its creators. A technical author who is part of a development team and process can use documentation to help shape the product itself.

The author and the development process

We are hiring dozens more technical authors. Our job advertisement says that part of the role is to “influence the development of Canonical products and services, as an expert user who has important opinions about function and design.” Amongst the nice-to-have skills: “User-experience, interaction or visual design”.

Technical authors receive design training, and work closely with their counterparts in Design. They are expected to bring design skills and thinking into their work in engineering teams.

This is not a typical arrangement, though many candidates for the role respond very positively when they learn about it. One of the observations they often make is that their work would be more effective, and the documentation outcomes better, if they could be involved in the product development process much earlier. They consistently describe the frustrations of having to create documentation for a product when it’s already too late to do a good job in time. They are happy to hear that we place technical authors right at the start of the development process. 

Why we do this

But, that’s not why we do this. We don’t do it so that they get more time to write good documentation (though that is also a desirable outcome). We do it because documentation is part of the product, and technical authors need to be part of the team that creates a product.

So, a Canonical technical author takes an active part in an engineering team’s stand-ups, alongside their developer colleagues, and takes part in conversations about the design and development of the team’s products. 

In fact, a documentation author is in a special position to understand the quality of design in a product, and to see things that their colleagues cannot. 

Any development team sees a product from the perspective of how it should be. They have an idea in mind, that they are busy turning into a reality. Their work is driven by it; the product, in their thinking, is that idea. Its workflows and internal logic are all framed by ideas that precede the reality of the product – which is why they are often astonished when they see actual users’ encounters with the product, and dismayed that users don’t share their mental models of it, or struggle to grasp them.

The problem is not so much that those ideas are allowed to remain implicit or unchallenged (though that can happen too), but that the creative minds of a development team have to stay in the world of those ideas. The shared assumptions that frame conversations, the leaps of logic and imagination they must take, even the language they adopt to carry their thoughts and work forward, all establish a mental world – one that becomes very difficult to step outside.

The work of documentation on the other hand is to express the idea of the product, in words, for people outside the hermetic world of the development team. The author, documenting a product’s interactions and workflows, physical sequences and logical relationships, exposes them to a different kind of light. 

A merciless kind of light 

Everyone knows the experience of having a fine idea, that when it has to be spelled out in words, suddenly looks a bit less splendid.

This is what documentation does. Documentation is a clear and merciless kind of light. Under its harsh scrutiny, many aspects of a product can look ugly, or clunky, or disjointed.

Often, the first person in a product team to realize that there is a problem with a product is the one who is trying to create documentation for it.

For example:

• It becomes inescapably obvious that it’s impossible to write an elegant account of a workflow, because the workflow itself is inelegant. 
• Or, perhaps a certain conceptual picture looks clean, until all the unspoken assumptions that were shoring it up are made explicit. 
• Or, in the act of describing a new feature in a CLI or API, it becomes apparent how inconsistent it is with the way existing features work, or even that the entire interface was created without any guiding principles.

Almost every technical writer who has worked in software has had experiences like these – but typically, the technical writer’s job is to do what they can with what they have been given: at best, to help the user deal with the product’s design flaws; at worst, to try to obscure the failures, brushing over the illogic they find.

This is a missed opportunity. At this point the technical writer should be empowered to have a voice into the product: “I am having trouble creating good documentation for this, because it is not as good as it should be”, with the expectation that this will be taken seriously.

But even this is a bit late. A technical author who participates in the conversations at the inception of a product or feature, who is working with the ideas and thinking about how they will be documented, and obliging their developer colleagues to think about those things too, is in a position to make these interventions much earlier.  

So, we want our technical authors to make use of their special position. We want them to perform a design function, and bring design value into products. They receive training, in design, user experience and user research to help them think about it more deeply about these domains, and perform that function more effectively. They are present in design conversations. We need technical authors to apply design thinking to product engineering work, and engineering teams to find a way to make use of their insights.

Outcomes 

The results are visible in our products and their development. Some of it is at the level of small details, already a sign that things are being noticed and improved that might have otherwise been overlooked; some of it is at the level of the definition of the product itself. 

There is new work on help command output in Multipass. In Juju, the Data Science Stack and other products, technical authors have made a difference to existing and new CLI features and the definition of APIs.

For Charmcraft, Charmhub and Anbox Cloud, recent design and user experience/research training have given authors ways to articulate a more useful critique of user journeys and user-facing tools in those products, so that problems and weaknesses can be addressed as engineering issues.

In another product, not yet publicly released, the presence of the technical author in design conversation meant they were able to draw attention to how a proposed pricing model would have implications for a successful tutorial experience.

And so on. When documentation and the people who create it are given the opportunity to be part of its design, and are given the skills and knowledge to perform that function more effectively, we consistently see value being brought to product development. And this pattern is one aspect of the technical authority that makes a technical author.

Find out more about technical authors

If you’re interested in joining Canonical’s team of technical authors, we’re hiring technical authors at all levels, for many different teams – we have dozens of positions to fill.

If you’d like to know more about what technical authors do, directly from them, you can meet them via the Canonical Open Documentation Academy.