Documentation: why, what... and for whom


3 minute read

At Friday we work in cross-discipline collaborative teams: strategy, design, UX, front-end, content, back-end and client might well all be in the same room for much of the project, not just formal meetings.

A lot of what we do is resolved in discussions and expressed in sketches. So we have to capture the essence of those discussions and especially the decisions the teams make.

We don’t work in isolation, so there is no need for massive documentation that describes everything about a project to hand on to the next team, who has to read it to find out what the project is, why it exists and what their role in it is.

Clearly we can’t get away with zero documentation, but what should be documented, how and for whom? And how do you know when you’ve got enough of the stuff? Here are eight lessons we’ve learned in the past couple of years.

The primary purpose of documentation is to share understanding.

The team needs to understand the purpose of what it is building, why it should exist (i.e. the user need) and what each individual is required to do.

Transparency is important; don’t work in closed boxes.

Documentation tracks progress: decisions documented are decisions that stick. Without documentation, it is easy for people to forget. And it reassures clients by ‘showing your working’.

You can’t capture everything, nor should you try.

Don’t create a massive tome of specifications; no one will read it. How do you know when you’ve got enough? When people downstream can do their jobs with minimal start-up effort and handholding.

Machines follow specs; people interpret contexts.

Yes, you need to document specification, but you also need to document context so people can make intelligent decisions.

Documentation needs to be accessible and visible.

Visibility can be achieved with very basic tools.

On one project we took the requirements document, chopped it into phrases that fit on post-its, stuck them on the wall, identified patterns and prioritised them. Everyone could see at a glance what they were supposed to do, why, and how their role was part of the wider project.

You can’t write without knowing who your audience is.

So target what is captured and how it is documented to a specific audience, a user group or team to ensure it is relevant. Bear an individual reader in mind. Ask yourself, who needs to know this? Don’t assume everything is best expressed in narrative form. Ask yourself, how will they best absorb that information? In text, slides, diagrams, video?

For example, the content-behaviour rules for a system were originally written by the content strategist and UXer in a series of declarations, e.g. “when the user views product x, the system also displays editorial content type y or type z or type n, in that preference order depending on availability. The Sitecore integration team scratched their heads and rewrote it as a flowchart.

Documentation isn’t static.

Our component library is a form of documentation which holds knowledge about components in the context of their use.

If you don’t document sufficiently the project slips and creeps.

You risk knowledge getting lost and decisions being repeated, repealed or constantly reviewed. No one learns and the project becomes more dependent on individuals’ retained knowledge. Ultimately the wrong thing might be built because people are unclear as to why they are doing what they do.

And if we had to boil all this down to a top three, it would be these: share understanding, not just specifications; document for a specific audience in the language and format they relate to; don’t try to capture everything.

We’d love to hear your experiences of documenting projects whether you agree or disagree. And please add to our list.


View all thinking