Twelve principles of documentation

Three general principles

The function of documentation is to serve the practitioner of a craft.

A craft is a domain of skill. Documentation exists to guide someone who needs to acquire and apply a set of skills. Documentation is successful to the extent that it addresses their needs.

A craft or domain of skill can be narrow, defined by the use of a product or tool, or wide, defined by a discipline or profession. (Examples of a craft: using a programming language, dress-making, piloting a particular aircraft, being a pilot in general.)

The function of documentation defines its architecture.

Documentation requires an architecture - a structural form - that serves its function. This structure must reflect a systematic understanding of skill itself, and the needs of a practitioner in a domain of skill.

The Diátaxis documentation framework is based on an analysis of skill across two dimensions: theory/practice and acquisition/application, and uses this to define an architectural map of distinct documentation types that stand in relation to each other.

Any given piece of documentation belongs in a single correct place within the whole.

For any piece of documentation, it should be possible to determine its appropriate place within the structure and its relation to other documentation content. It should be possible to do this with confidence, using precisely the same logical principles that determine documentation architecture.

Four product documentation principles

In the case of a product, documentation is part of the product itself.

To the extent that a product lacks documentation its users need, it is not merely less usable, but literally incomplete.

A product’s documentation must form a self-contained, unified whole.

A product’s documentation should be a body of work with a common purpose and scope, conceived, written, maintained and presented as a coherent unit.

All material aspiring to the status of documentation needs to be integrated into this body of work.

Product documentation has intentional scope.

Product documentation is not merely a collection of written material related to the product. It must be purposeful, intentional and developed according to a vision that accords with a vision of the product’s own purpose and intent.

Product documentation has a life-cycle.

For products that evolve - such as software products - documentation has a life-cycle. The life-cycle of documentation includes its creation, review, maintenance and expurgation.

Documentation that is created, but not reviewed, updated or deleted, is worse than useless.

Five documentation management principles

Duplicated content loses authority.

There can be only one source of truth. Permit any piece of documentation content to exist in one context only.

(Though it can be tempting to duplicate a portion of some product documentation from one context to another, this effectively guarantees its diminished authority across all its instances.)

Documentation sharpens under pressure.

Whether it comes from exposure (references and links to material that ought to be better than it is) or from expectation (users’ demands) pressure forces documentation to improve. Documentation should be subjected to the maximum possible exposure and expectation.

(It’s tempting to make up for a lack in documentation elsewhere by brushing over its defects or making up for it elsewhere. This may reduce temporary embarrassment, but it also reduces the pressure that leads to improvement. It’s part of a vicious spiral in which documentation tends not to be improved.)

The time to start is now.

It is never too early in the life-cycle of a product to start creating its documentation. When you have something that can be documented, start writing. When you have something written, publish it.

(It’s tempting to wait for the right moment, for when you or something else are “ready”. This is part of - and compounds - a mistaken attitude that documentation follows the product it refers to. In fact creating documentation is not only part of getting to “ready”, it helps get there faster, and to a better version of it.)

Documentation without a plan for its maintenance is condemned to rot.

Documentation is guaranteed to decay unless there is an explicit, effective programme in place to maintain it. No documentation should be created that will not be maintained.

(Often, creating some ad-hoc content that meets some immediate need seems like a good thing to do - and it can be, but never in documentation. There are other ways to publish such material.)

Connections in documentation are part of its robustness.

Well-considered links within and between documentation form a powerful network of knowledge, in which all the parts help sustain the others. Take every opportunity to build this network.