2017 award 1st rank

2017 FrontMatter Award Winner

JExtensions Store logo

 

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.

The incomplete bridge. By Mark Baker

Written by The News Aggregator
Category: Content & Communication Published: Friday, 22 September 2017 08:31
Hits: 104

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. […]

 

Quote:

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.

 


Read full article on Every Page is Page One

About Mark Baker

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).

 

  Your current access does not permit you to view the comments under this section

PROMOTED

My Battle with Fake Social Media Accounts. By Agnes Banks

I am always amazed by the number of colleagues who accept invitations from fake accounts on LinkedIn. This, without checking…

The incomplete bridge. By Mark Baker

On Every Page is Page One:In the Top Gear Patagonia Special, the presenters come upon an incomplete bridge and have…

Global Content Strategy: A Primer. By Val Swisher

On The Content Wrangler: Our world revolves around content. These days, buying decisions are often based on experiences not with products,…

Let The Robots Do The Work. By Tom Johnson

On I'd Rather Be Writing: "Write the Docs Podcast Episode #7: in this podcast, we first explore the flourishing community…

The problem with Frequently Asked Questions (FAQs) in documentation. By Tom Johnson

On I'd Rather Be Writing:"On Many tech writers have a heavy disdain for Frequently Asked Questions (FAQs) in documentation. At…

The future of ad blocking. By Arvind Narayanan

On Freedom to Tinker: "There’s an ongoing arms race between ad blockers and websites — more and more sites either…

In Praise of Long-form Content. By Mark Baker

On Every Page is Page One: "Yesterday I wrapped up work on my new book on Structured Writing and delivered…

Who Has All the Content? By Roger C. Schonfeld

On The Scholarly Kitchen: "Our contemporary media landscape is characterized by fragmentation. Every publisher seemingly has its own platform, and…

Technical Writing Trends and Predictions for 2017. By Tom Johnson

On I'd Rather Be Writing: "My 2016 technical writing trends/predictions turned out to be pretty accurate. For 2017 technical writing…

 


 

 

If You Like What you See

 

If you would like more people to read it, here's what you can do to help spread the word: 

♦ You may use excerpts and links, provided that full and clear credit is given to the author of the article and with specific link direction to the original content [frontmatter.com/...]

♦ To use and/or duplicate, reproduce, distribute, translate material from FrontMatter content,  or content from an author and/or owner, you must request a written authorization and read the FrontMatter Terms of Use.

If you read our original content and like it, support us, donate, and join us to contribute content.