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.
Good post Mark — Glad to see more.
I am also glad to see you praise text! I agree that we have been hearing about the death of text for years, and yet it still carries on. Your two points — that text is asynchronous, and is discoverable — are spot on.
I’d like to add a third aspect of text — It is combinative. The act of creative thinking is an exercise in combining existing parts in new ways to come up with an innovative new “thing”. Text mirrors this when it enables you to combine existing texts in new ways to arrive at innovative realizations. The purest form would be mathematics, where you can use new combinations to model gaming, macro economics, or the universe itself. But prose is no different — William Burroughs played with cut-ups, novels have been written on decks of cards that are meant to be shuffled, and hypertexts are fundamental to gaming-as-literature.
With the structure and concrete references we use in technical documentation, there’s every reason for machines to exploit combination to build even better texts to match a given situation.
Text will carry on, and it will always support what people do best — combine parts in unique ways to arrive at innovation.
Combinative! Yes. I knew there was something else I wanted to say on that subject but le mot juste escaped me. But that is it, precisely. Text is combinative. And that is one of the reasons linking is so important: it exploits the combinative possibilities, or at least some of them.
Great post once again, thank you Mark! Oh, but it‘s either Nürnberg or Nuremberg. “Nurnberg” is … well, combinative 😉 Greetings from Germany
Thanks for the comment, Lars.
John Carroll did not use the umlaut in the title of The Nurnberg Funnel, so I copied his usage. Always a bit tricky when the only difference between an anglicized word and its original is just a diacritical mark.
You’re right, I know Carroll’s book but never noticed that. Somewhat ironic that a book about knowledge has a mistake in its title.
Hi Mark,
An incomplete bridge, what a wonderful metaphor! And what an elegant way to explain what technical communication is.
I always have to scoff at the metaphor of the technical communicator as a bridge between the technician and the user, because, in my experience, no technical communicator is that good.
Many technical communicators experience the cognitive dissonance of not being able to do what is in their job description and live in the resulting lack of self-confidence. A surprising number of workshops, articles, podcasts etc. in tech comm are dedicated to convincing techical communicators that they are worth more than they think.
Of course the cognitive dissonance melts away if you adopt the metaphor of the incomplete bridge. The user needs to do his part, too.
Having said that, I am not so sure that text is as virtuous as you describe: it still is a substitute for experience. Often, you can understand written instructions only after you already know what they mean. You can read about driving cars as much as you want, but you will not learn to drive until you are behind a steering wheel. With an instructor next to you for your and other people’s safety.
For maintenance instructions, the types of documentation I write, I believe a certain amount of learning-by-doing during trainings is necessary.
I agree that text is a poor substitute for experience. We use it because we can’t ship experience. The role of text is to support, prompt, and reassure us as we venture into the realm of experience, which is, of course, another way in which the bridge is necessarily incomplete. This is, of course, exactly what John Carroll was saying in The Nurnberg Funnel.
And yes, it is a shame that technical communicators are sometimes judged against a standard that is impossible to meet — truly impossible, that is, not merely too difficult. We cannot realign neurons in the reader’s brain, we can only support, prompt, and reassure as they go through the process of realigning them for themselves. The double tragedy of that is that technical writers are often made to feel their work is unsatisfactory and that they often make it worse trying to make it do more that it can.
Text is NOT a poor substitute for experience. Text is a COMPRESSION of experience. Which would you rather have to rely on, a sign “Warning, HOT!” or the pure experience? Not all experiences can or should be compressed. But for those that can, we gain enormous value for them having been compressed and stored for posterity. How else would we know Socrates (ironically enough) or Kepler?
Compression is an interesting choice of words, but that is really taking it up a level and talking about story. Story is a vehicle for evoking experiences based on memory. “Warning, HOT!” means nothing until the first time you burn yourself. Text is the most versatile medium we have for telling stories, though it is certainly not the only one. The properties of text that we are interested in for current purposes have more to do with navigability.
So, perhaps both disc_writes and I should have spoken in terms of stories. Stories are a substitute for experience. They are less effective for teaching than experience itself, but they have many other virtues, such as being much safer and much more shareable than experience.
The fact that stories work by evoking experience, and that people have different experiences and tell different stories about those experiences is a huge part of why the bridge is necessarily incomplete. Text is a useful format for building the writer’s part of the bridge because of it generality and navigability, which make it easier for the reader to find or construct the stories they need to complete their part of the bridge.
Fundamentally, the bridge is made of stories. The writer tells their stories in a recorded public fashion. The reader (mostly) constructs their stories in their head. It is the writer’s public stories and the reader’s private stories that together constitute a complete bridge.
Spot on with the notion of the author’s stories and the reader’s stories bridging the communication gap.
I can’t agree that a compressed experience (as I would call it) is meaningless without a direct reference to a personal experience. WARNING HOT is meaningless unless you have burned yourself? More accurate would be that it’s meaningless unless you know (directly or indirectly) the consequences of disregarding that category of message. Otherwise WARNING BIOHAZARD would be disasterously ineffective. Ultimately there’s a personal connection, but the magic of text (well, language in general) is that meaning can be abstracted away from my body by many degrees.
I’ll never experience the methane rain on the moons of Saturn. Or a supernova. But I still get meaning out of those stories.
On the flip side, I have experienced the transport of substances through my cell walls, but I might as well not have… There’s a level where that experience is totally meaningless until I hear a story about it.
Oh, certainly, stories allow us to learn by analogy. It is a key feature of our brains that the experience of touching a hot stove as a kid can enable us analogically to appreciate how much worse it would be to stick your head in a furnace. It is because we can extrapolate from the experience of having a cold that we know we don’t want to mess with stuff marked BIOHAZARD. You have experienced rain and seen the sun. Your understanding of methane rain and supernovas is by analogy from those experiences, which is how you get meaning out of those stories. This is why stories are capable of forming bridges, because we are capable of analogical extension of experience through story.
If we did not use stories in this way, it would be impossible for us to survive or to progress. Stories build bridges because they are able to span the gulf of things that we cannot directly experience.
Mark, I really do appreciate these and your other thoughts about stories, experience, text and so on, but sometimes it seems to me like you’re trying to reinvent the wheel. I mean there’s narratology, there’s hermeneutics, there’s phenomenology – thousands of people have thought and written about those things for hundreds of years. Maybe you’re aware of that and just leave out the references, but even if you do, it might be useful to follow up more on existing and established theories and transfer them to the field of technical communication.
Lars, indeed, there is nothing new under the sun. But once you get down into those weeds you will be there for a very long time and there is not much chance that it is going to change how you work day to day. (You must have noticed that the theorists of communication are themselves abysmal communicators, at least for the most part.) This is not to say that there is no value in all that work, but to realize much of that value, you have to simplify a idea down to the point where it is simple enough to be used.
This, of course, comes down to building a bridge that is close enough and has enough familiar reference points for people to build their own bridges to. That work is seldom done by the scholars of the grand theories or even their students but by the students of their students.
One of the things that we should learn from the theory of stories is that stories have to be retold and retold in different ways to reach different people. I am somewhere in the middle of that chain of storytellers on this subject. If someone else wants to say, “Baker is talking about hermeneutics,” that’s fine with me, but I am not going there myself. My place in the story chain is elsewhere.
@Lars… For me, text as compression relates to information theory… Text is a signal that uses fewer data points to represent an event, or to represent a data set that has recorded an event. If you read and understand the text, you can expand it out to approach the original data set, or at least as much of the data set that you need in order to demonstrate your understanding. (Yeah, it gets pretty foggy right around there, but it’s how I like to think about what I do for a living.)
I think stories are the similar, but the nuance is directed more toward cultural anthropology… I definitely shouldn’t try to speak for Mark, though.
I think stories is getting at something similar. The way I look at it, stories are built of reference to other stories. So it is stories all the way down to a base of actual experience. I don’t know if I would call this compression exactly. To me it is simply the way language works. We attach words to stories and stories to experiences so that by simply uttering a word like “agile” or “Web” or “Corn Flakes” we bring a whole host of associations into the reader’s mind instantly.
It’s not just individual words that do this, though. We use small snippets of story to evoke much larger more detailed stories, sometimes directly and sometimes by analogy. So when we say “home run” or “own goal” or “visited by three ghosts” or “one ring to rule them all” we are bringing in a whole raft of stories and relying on our readers to contextualize them to the thing we are talking about.
The reason I am hesitant about “compression” is that while this process does compress in the sense that the ability to pull all these associations by reference, which certainly compresses the message, it is also a rather unreliable mechanism. It is hugely economical, and without it we would hardly be able to communicate even the most simple idea. But because it relies on the recipient to figure out how all these references go together to form the story we are telling, it is inherently imprecise. The problem is not so much that the result is compressed but that it is so full of extra implications which the reader has to intuitively filter out. (Another reason why the bridge is incomplete.)
One of the implications of this inherent imprecision of language is that good communication involves a degree of triangulation. You attempt to invoke in your reader a set of memories and associations which individually are broad but which have a much smaller area of overlap which serves to shrink the potential set of meanings to be received.
Another way this triangulation gets done is in conversations like this one. Conversation is, of course, two people building bridges towards each other by a process of iterative refinement, continuing until they meet or one or both parties gets frustrated and decides to burn their bridge.
Oh, yes, I knew there was something else I wanted to say on this subject. As far as demonstrating one’s understanding goes, I think it always comes down to action. That is, you can think that you both understand the same stories in the same way, you can pass tests in which the stories you tell are the stories that the examiners want you to tell, but until you take actions based on the stories you believe, we don’t really know if you think the same way at the people who told you the stories.
We have all, I am sure, known cases in which people did things that were utterly contrary to what we thought we had said, only to have the reply indignantly, “but your said…” to which you responded “yes, but not …”
This is part of the uncertainty of stories, which is essential to the efficiency of communication. The efficiency of communication is based on the assumption that the way you recieved the story is the way that I intended the story to be received, but we never know that for sure until you try to act on the story and I observe whether you acted as I would have expected someone to act given the story I told.
This, in a sense, parametrizes the notion of accuracy in communication. If your understanding of the story is close enough to my understanding of the story that you act in the same way that I would act in the same situation then my transmission of the story is sufficiently accurate for all practical and discernable purposes.
That does not mean that the story I told is the story you heard, only that they are close enough to result in the same action in all cases heretofore observed. And that is as close as it is possible to get to truly knowing if the story was transmitted accurately.
It is entirely reasonable to suggest that no story is ever received entirely as it was transmitted, because the only way to judge the quality of the transmission is to observe actions consequent on the reception of the story, and that is not enough in itself to prove that the transmission was perfect. We might well choose the same action for different reasons.
Which means that the highest attainable standard of technical communication is “sufficient to produce the intended action”.
I’m sharing this! I’m sharing this!
I learned about you from Content Writing 101, for which I’m grateful. I’m a subscriber now, so try not to wait four months to post again. 🙂
Seriously, congratulations on getting your book written. I quit blogging about five years ago to finish a book and haven’t blogged since. (That might be a good thing.)
Hi, Mark – I am a novelist and aspiring tech writer, but I’ve been aspiring for 30 years. I came across your site doing research for the “tell the story” thing in tech writing. My manager keeps telling me to tell the story, but there is no story, it’s a device, for cryin’ out loud! But, an article on the IEEE website made me think differently. I’ve bookmarked your blog, so you may get some angry emails from those who I tell “Mark Baker says…”
Sorry I did not see and approve your comment earlier, Larry. I’m not here very often these days.
Part of the role of story in technical communication is that the user has a story about what they are trying to accomplish, and a story about how the tools they use to accomplish their task are supposed to work and what role they are supposed to play. They come to the device with those stories in mind, and if the device they see does not fit the story in their heads, they don’t trust what they are told about it. Sometimes, therefore, it is necessary to correct the story that is in their heads.
Technical communication is not just about the information the user needs to act, it is about the confidence that the user needs to act. There is so much bad documentation out there, and in many cases there is such a gap between the user’s expectations and the way the machine actually works that even good documentation, if it does not address the expectation gap, will not give the user the confidence they need to act.
I remember back in the early days of Macintosh, I was teaching someone the interface and when I told them to eject a disk by dragging it to the trash they flat out did not believe me. “That will erase the disk,” they said. They were convinced of this, despite never having seen the machine before that day. But earlier they had learned that you delete a file by dragging it to the trash. From this they extrapolated a story about what would happen when you dragged a disk to the trash. It was actually a pretty logical story.
Users come to your device with a story in mind, and form new stories as they use it. Tech comm needs to anticipate, engage with, and shape those stories in order to give them the confidence to act correctly.