7 Principles for Designing Help Topics in the Age of the Web
In this blog, our guest, Mark Baker, shares several revealing guidelines from his book “Every Page is Page One.” Now that so many of you are publishing to multiple screens via RoboHelp and Tech Comm Suite, it is time to rethink how we author topics or sections so that any portion of our project may be the first “page” the reader sees.
____________
We live in the age of the Web. Even if your help is not delivered on the Web, your readers are online, and their habits and expectations are formed by their experience of the Web. As Gerry McGovern argues, we don’t go online anymore; we simply are online, all the time.
Readers who live and work online, don’t tend to stick to one information source. Rather, they forage for information, quickly moving from one source to another looking for the strongest information scent. As Jakob Nielsen puts it: “ [T]he better search engines get at highlighting quality sites, the less time users will spend on any one site.” That includes your help system as well. Even if your help is not on the Web, the user is, and can very quickly search for other content if yours does not instantly satisfy.
Whether your help system is on the Web or not, therefore, you have to make sure it has a strong information scent to an information foraging reader, and that it really satisfies their information need in a way that keeps them from wandering off to forage elsewhere.
When readers are free to roam across the Web, each piece of content they encounter becomes a new page one. There is no forward, next, up, or down on the Web. Every page is page one. Making content work on the Web is about more than making it brief or eye-catching. For content to work on the Web, and even off the Web (when the reader themselves is on the Web) it has to work as an effective page one for the reader. It has to be what I call an Every Page is Page One topic.
In my book, Every Page is Page One: Topic-based Writing for Technical Communication and the Web, I describe seven essential characteristics of an Every Page is Page One topic. These characteristics serve as guiding principles for designing help content in the Age of the Web:
Principle One: Topics should be self-contained
https://blogsimages.adobe.com/techcomm/files/2013/10/nesting-dolls.jpg
In the Age of the Web, a reader can come to a topic from anywhere. They don’t necessarily encounter it as part of a book, part of a help system, or part of a website; they encounter is as an information product in its own right, a new page one. To act as an effective page one, a help topic must be self-contained. It must not rely directly on a previous or next topic, or on a hierarchical table of contents. As we will see, it may rely on the entire information environment in which it is embedded, but it has no specific dependencies. It is self-contained.
Principle Two: Topics should have a specific and limited purpose
A successful topic must have a strong information scent. To do this, it must serve a well-defined purpose that the user will quickly recognize. Of course, a topic can’t anticipate everything that any user might want to do, nor every way that a user might express their purpose. A topic will have to serve the purposes of many different users with many different objectives (just as a bus route serves many different riders going to many different destinations). Trying to bend a topic to serve every single user’s exact motivation can actually twist it so out of shape that its information scent becomes confused and it works for nobody. The key is to be very clear to the user exactly what purpose the topic does serve so that they can make a good decision about whether the topic is going to help them reach their objective or not.
Principle Three: Topics should adhere to a type
The idea of structured writing and writing to a fixed pattern can seem uncomfortable and confining to many writers, and if the types are poorly designed, it can be. But if you look at Every Page is Page One content on the Web and elsewhere – content that is self-contained and serves a specific and limited purpose – you will find that it almost always naturally conforms to a type.
This is not surprising really. If a topic is self-contained and has a specific and limited purpose, it is likely that it will have the same content fields as other topics on similar subjects. The things you want to know about one recipe, you want to know about all recipes. The things you want to know about one API, you want to know about all APIs. The type of a topic is a direct result of its purpose.
Defining types for your topics, whether you do it using structured writing techniques or simply by defining templates, will help give your content a stronger and more consistent information scent and help to make sure it fulfills its specific and limited purpose.
Principle Four: Topics should establish their context
In a World where every page is page one, readers can arrive at your topic from anywhere. Even if they find it using your own help system’s search, they still arrive without knowing the context they have arrived in. Establishing context is essential if your reader is to recognize where they have landed and determine if they are where they need to be.
It is easy to assume that the reader will already be in context before they get to your content – that they will know where they are because they followed the table of contents, or read topics in order, or hit the help key in an application context. But you can’t rely on this, especially if your help is on the Web. You have to allow for the reader arriving by search or by following a link.
Clearly establishing context, both with a good title and a clear opening paragraph, is essential to establishing a clear information scent for your topics that will attract readers and keep them from leaving your content for greener pastures.
Principle Five: Topics should assume the reader is qualified
https://blogsimages.adobe.com/techcomm/files/2013/10/DIPLOMA.jpg
An Every Page is Page One topic should assume the reader is qualified. This can be a difficult idea for technical writers to accept, because we have been trained not to assume that the reader knows as much as we know, or as much as the subject matter expert knows. But while that is still true for the documentation set as a whole, we can’t write individual topics that way. Different topics may serve the needs of different individuals with different levels of knowledge, but each individual topic needs to be written on the assumption that the reader is qualified to read it and to perform the task it describes.
The reason for this is simple: without this assumption, the topic cannot stick to its specific and limited purpose or follow its defined type. By adding in additional information for unqualified readers it will become bloated and unwieldy. It will cease to have a strong and clear information scent.
Consider a recipe. A recipe may contain instructions like “sweat the onions,” “separate the eggs,” or “whisk the cream”. These are all cooking terms that not everyone attempting the recipe will recognize. But the recipe does not stop to explain every cooking term and technique. If it did so, it would be long, complicated, difficult to follow, and annoying for experienced cooks. Instead of the recipe catering to the unqualified reader, it leaves teaching basic cooking to other sources.
Every Page is Page One help topics must do the same. They must assume a suitably qualified reader and write for that reader. The help system as a whole should provide other topics to bring unqualified readers up to speed (or rely on the wider information environment of the Web to do so), but individual topics should be written for the qualified reader.
Principle Six: Topics should stay on one level
In books, it is common for the author to change levels. One author may start with a high level overview and then dive down into detail. Another may start with a detailed example, and then generalize from the example to illustrate higher-level concepts. Either way, it is the author who is deciding when and how to change levels.
But an information foraging reader has their own ideas about what level of information they are hungry for at the moment. They can and will choose when to change levels for themselves, and if you try to change levels when they are not ready to, they will lose the information scent and wander off to forage elsewhere.
An Every Page is Page One help system, therefore, should allow the reader to decide for themselves when to change levels. This means that each individual topic should stay on one level, allowing the reader to change levels when they want to by moving to another topic. Once again, this helps to ensure that each topic has a strong and consistent information scent.
Staying on one level is also essential to the other principles. It is difficult for a topic to be self-contained, to have a specific and limited purpose, to establish context, and to stick to addressing a qualified audience if it does not stay on one level.
Principle Seven: Topics should link richly
https://blog.adobe.com/media_16e3c2ff22274d9b2a5a9281fbcd068d07461bfa.gifWriters often have mixed feelings about links, fearing that they will distract readers from the content they are supposed to be reading. But in a world where every page is page one, and the information forager has the Web at their fingertips, there is no way to keep readers in your content except by continuing to nourish them. Boredom and hunger, not links, will distract them from unsatisfying content.
And since your readers will often need to access other topics because they need to understand some concept you have mentioned (assuming them to be qualified) or wish to switch to more general or more detailed level, you should be providing them with the means to do so.
Failing to provide them with links won’t stop them from going off in search of background information or from changing levels when they want to. If you don’t provide links, they will use search. But search is more disruptive of their thought processes, and it may well lead them out of your content, perhaps never to return. If you provide them with useful links that keep them within your content (where appropriate) you will serve their needs better and keep your customers in your own content set.
Conclusion
In my book, Every Page is Page One: Topic-based Writing for Technical Communication and the Web, I explore each of these principles in depth. I also provide an in-depth look at how the Web changes the way readers look for and consume information, and what it means for technical communication. In particular, I look at how to go about covering a large product or service adequately using topics and how to deal with issues like workflow and the big picture.
The modern reader is more likely to look for an information snack than a full meal, especially when they are trying to solve a technical problem or to get your product to do what they want it to do. Writing help topics that follow the seven principles of Every Page is Page One will allow you to create a help system that has a strong information scent to attract readers and that also provides them with a satisfying snack that quickly sates their hunger.
About out guest blogger:
https://blogsimages.adobe.com/techcomm/files/2013/10/BAKER-HEAD-SHOT1.jpg
The Web changes how people use content; not just content on the Web, but all content. If your content is not easy to find and immediately helpful, readers will move on almost at once. We are all children of the Web, and we come to any information system, including product documentation, looking for the search box and expecting every search to work like Google. There is no first, last, previous, next, up, or back anymore. Every Page is Page One.
For technical communicators, this Every Page is Page One environment presents a unique challenge: How do you cover a large and complex product using only topics, and how do you enable your readers to find and navigate topic-based content effectively?
In this ground-breaking book, Mark Baker looks beyond the usual advice on writing for the Web, and beyond the idea of topic-based writing merely as an aid to efficiency and reuse, to explore how readers really use information in the age of the Web and to lay out an approach to planning, creating, managing, and organizing topic-based documentation that really works for the reader.
– See more at: http://xmlpress.net/publications/eppo
One way to get to “page one” … RoboHelp 10
To find an effective way to publish “anywhere / anytime”, you may wish to have your own hands-on with RoboHelp. The quickest way to do this is to have use a trial copy of Tech Comm Suite 4, which includes FrameMaker 11 and RoboHelp 10. You can try your own hands-on by clicking here. This link also includes a link to a Quick Start Guide for RoboHelp.