In the Top Gear Patagonia Special, the presenters come upon an incomplete bridge and have to construct a ramp to get their cars across. This is a great metaphor for technical communication, and, indeed, communication of all kinds: the incomplete bridge.
Technical communication is often described as a bridge between the expert and the user. But that bridge is always incomplete. The user always has to build the final span that connects the bridge to the bit of ground they are standing on.
This is true for several reasons, the most basic of which is that you have to contextualize any information you receive to your own project in order to act on it confidently and successfully. If the document tells you to push the red button, it is still your job to determine if you are looking at the right device and the right red button, and if your purpose will truly be served by pressing the red button at this time. The document can never entirely ensure that you do not press the wrong button on the wrong device or at the wrong time for the wrong purpose. Only the individual reader can determine those things, and thus only the reader can build the final span of the bridge.
But the reader may need to build more than that final span of context. While the writer can do a lot to make sure they understand the class of people to which their target set of readers belong, and thus to use vocabulary that the users use the way they typically use it, they cannot guarantee that the piece is written in the vocabulary of each individual user. Inevitably some users will have to build some vocabulary spans for themselves some of the time.
The same goes for broader issues of task and craft knowledge. The piece may be written for experienced practitioners of a particular craft, but even experienced practitioners may not be familiar with every task in that craft (you might cook for years without ever separating an egg or blanching a carrot). References to these tasks and other aspects of the craft that the reader is not familiar with are other spans that the reader needs to construct for themselves.
In short, while the bridge the writer builds is always somewhat incomplete, it can be a good deal more incomplete for some readers than for others. Thus there will always be a significant section of the user population for whom the documentation sucks. The bridge will always be incomplete, and the ability and willingness of the reader to build the missing spans for themselves will vary widely.
This has some very important consequences for technical communication (and communication generally).
The first is that you cannot make it perfect. You have to design your documentation set with reasonable and achievable goals in mind and you cannot set those goals in terms of perfect and effortless performance of every task by every user. This does, of course, make the setting of goals and the measurement of performance much more difficult. But setting unachievable goals is not a recipe for success. This is why the Every Page is Page One principles of defining a specific and limited purpose and assuming that the reader is qualified are vital to keeping a project from going off the rails.
The second is that if you keep adding things to your bridge you are more likely to make it impassable than to make it more accessible. The old London Bridge was so overbuilt with shops and houses that overhung both the river and the roadway that it was severely congested and took over an hour to cross. Not to mention that the additional weight of all those buildings caused frequent collapses.
Overbuilding your documentation set will not reduce the effort that readers have to put in to fill in the spans they need to contextualize the content to their task or to bridge the gaps in their own experience and knowledge where it differs from what the document assumes. Clearly, of course, a bad document can end up a bridge to nowhere that no one can access and no reader is willing to invest in building spans to complete. A good document does all that the writer reasonably can do given the diversity of their audience and their inevitable ignorance of each reader’s individual circumstances. But building more stuff on top of that reasonable document will make it worse, not better. It will make it less passable, not more accessible.
The third consequence follows. Since a reasonable document is designed with the knowledge that it is an incomplete bridge, it should be designed and presented in a way that facilitates as much as possible the bridge building activity that the reader has to do for themselves. This means that it has to leave room for the intellectual work that the reader will need to do in order to make use of the document.
It is fashionable today in tech comm circles to talk about the next wave of user assistance taking the form of chat bots or digital assistants such as Alexa. Of course, this is not the first time we have been told that text is dead. People have been saying that ever since the VCR went on sale, but while YouTube videos are now a major part of the total tech comm landscape, they have occupied a niche to which they are well suited; they have not put an end to textual documentation. Alexa and the Chat Bots (cool band name!) won’t put an end to it either.
While conversation with a machine is cool in its way, it is the audible equivalent of a command line interface. There is no territory to explore. There is no discoverability. The basic lesson of the graphical user interface is that the user can get on faster if they are given an environment that is easier to explore. Exploration is, of course, the user building their end of the bridge.
Conversation is a form of mutual bridge building as well, each person adjusting what they say and how they say it in order to get across to the other person exactly what they are trying to express. But even where conversation is available to us, we often prefer to go away and study and work on a problem for ourselves. Getting our minds to the point where the last span is complete and the last spike is driven is not merely a matter of an exchange of information, but of a maturing of mental models in the individual mind. That takes time, and a unique exploration of the problem space by the individual doing the learning. There is no Nurnberg Funnel. Each reader has to build their part of the bridge for themselves.
The virtue of textual documentation for this process is first that it is asynchronous. We can absorb the lessons of text at the pace our own minds are working at at a given moment. The second virtue is that it is discoverable. Text, particularly in the form of a mature hypertext, creates an environment that the reader can freely explore for the unique parts they need to build their own bridge spans. Google and the Web, have, of course, greatly increased the discoverability of text. The best thing we can do to help the reader do their own part of the bridge building between their business needs and our products is to create content that is best suited to the hypertext/search paradigm created by these technologies. Every Page is Page One.