Work in documentation

I’m interested in technical documentation, including its practice, theory, organisational strategy and execution. I believe it should be a discipline based on rigorous foundations.

Documentation could be a user guide for a programming language or framework, or the operating manuals for a product such an electric toothbrush, a camera or an airliner. A handbook for conference organisers, or members of a team in a company would count too. I mostly work with software product documentation.

What all of the above have in common is that they are written materials that support a practitioner in a domain of skilled practice.

This definition places the user of documentation - the practitioner of a craft - at the centre of its concerns.

Diátaxis

I’m the creator of the Diátaxis documentation framework. Diátaxis is a systematic framework for technical documentation authoring.

Diátaxis describes an information architecture and approach to content that are informed by an understanding of the needs of users in their cycle of interaction with a product, or their practice in a craft.

Diátaxis - it’s like wearing glasses after having lived in a blurred world.

—Vincent Magnin, Polytech Lille

Diátaxis solves a number of difficult problems in documentation, most obviously the problem of structure. It’s popular because it’s easy to grasp and use, delivers quick results, and has a good name.

Documentation practice and strategy

Software engineering is a discipline, with standards, methodologies and rigour. The question of software engineering practice is never far from the mind of a professional in the field, and in an organisation, it’s a permanent part of the conversation about work. But documentation practice is notably - strangely - an absent concern.

No serious developer would ever consider “just writing code” to be an adequate approach to creating software. And yet, entire organisations in effect do exactly that when it comes to documentation.

At the same time, most software organisations recognise that they have serious problems with their documentation, that stubbornly resist attempts to ameliorate.

Over the last 10 years I’ve led the documentation efforts of companies (Divio, Canonical) as well as other organisations and projects, introducing systematic approaches to tackle systematic issues. The challenges are different in each case, but some themes recur, and some, quite clearly, are intrinsic to documentation itself.

Documentation extends across its subject matter, and though time. In the former case, the key to quality is structure - the architecture of the content itself; in the latter, its management of the documentation life-cycle.

Quality of documentation at scale doesn’t simply mean dealing with more of it. Scale adds a new dimension to the challenge. Good practice must become something that belongs to the organisation and its way of doing things, that is continually disseminated, reinforced and renewed.

An effective documentation strategy must have adequate answers to the questions of:

• standards of quality: a definition of good, that is understood and commands assent

• culture and discipline: an organisation-wide attitude of care

• execution: ways of working that make it easier to do the right things

• equipment: software tools that lessen burdens and cement good practice

You can find an outline of this way of thinking as applied to Canonical in The future of documentation at Canonical.

The approaches I bring are proven and transformative. They are scalable and maintainable, because they work with underlying patterns in documentation. They treat documentation as a discipline within its own right: a domain that functions according to its own particular needs and rules.

Workshops and training

I regularly run training workshops, usually to support open-source software projects.

See Events for forthcoming and recent events.

Enquiries from open-source software projects for coaching or workshops are welcome.

However I am not currently taking on engagements for paid documentation consultancy or coaching - sorry.

Documentation in open-source software

I’m indebted to many software projects that have solved my problems or otherwise improved my life. I repay that debt where I can by contributing improvements to the documentation of those projects, or providing training to contributors.

Some examples: Python, Django, pytest, django CMS, BeeWare, Wagtail. At the time of writing, I’m working with Rinohtype.