Content & Communication
2017 FrontMatter Award Winner
The FrontMatter Award Winner program honors developers who have excelled over the last years and helped frontmatter.com to be what it is today. This year's award was won by John Dagelmore of J!Extensions Store for providing superior and dedicated services.
On Every Page is Page One: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. It 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 as 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 when 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.
Mark Baker helps organizations improve the impact of their content by focusing their design, writing, and production processes on producing content that matches the way people seek information on the Web today. He is the author of Every Page is Page One: Topic-based Writing for Technical Communication and the Web. He blogs at everypageispageone.com. You can reach him through his company, Analecta Communications Inc. (www.analecta.com).
Wednesday December 13
On Medium: Acquiring your first 100k active users is an art, but a messy one—especially if you don’t have a lot of money to spend on marketing and paid acquisition. Winnie…
Wednesday December 13
On TechCrunch: Professional social networks like LinkedIn have long been a mainstay of business, but what if you are more of a creative bent where LinkedIn looks pretty stuffy? In the…
Wednesday November 29
On BetaNews: Most data thefts are down to relatively simple techniques, like phishing, in order to get hold of login credentials. But even where systems are well protected, hackers can…
Wednesday November 29
On BetaNews: Machine learning is taking the tech world by storm. Recently, an announcement that Google was open-sourcing Tensor Flow, their machine learning (ML) software, and Microsoft quickly followed suit. Baidu and Amazon unveiled their own deep learning…