Getting Past the Linear/Hypertext Hybrid

A lot of the information design being done in technical communications today is what I think we can fairly call a linear/hypertext hybrid. Perhaps this is a necessary stage in our evolution from static linear paper manuals to dynamic hypertext information sets, but if so we have lingered in it far too long, and we are still producing and using tools and systems that are designed for the linear/hypertext hybrid rather than for true hypertext.

This thought occurred to me when reading Tom Johnson’s post on collapsing sections. As I commented there, collapsing sections are a symptom of the linear/hypertext hybrid. They are hypertext in the sense that you have to click a link to open the section, but still linear in the sense that they are written and organized as part of a single consecutive narrative. As such they have some pretty significant problems, as I noted in my comment on Tom’s post. read more

Topics, Pages, Articles, and the Nature of Hypertext

What is the right word to describe a node of a hypertext?

What should we call the basic unit of information that we present to readers? Is it a page, a topic, or an article? (I’m going to take it as read that the answer is no longer “a book”. If you disagree, that’s what the comments are for.)

I raise this now because of Tom Johnson’s latest blog post, DITA’s output does not require separation of tasks from concepts in which he makes the distinction between topics as building blocks and articles as finished output:

One reason so many people mistake the architecture of the source files with the architecture of the output files is because the term “topic” tends to get used for both situations. I prefer to call the output files “articles” rather than topics. An article might consist of several topics. Each of those topics might be of several different types: concept, task, or reference. read more

Readers Express their Purpose in Terms of Tools and their Features

One of the samples of an EPPO topic that I included in my book was a topic from the WordPress Codex on the subject of Using Themes. One of the key properties of an EPPO topic is that it serves a specific and limited purpose. I identified the purpose of this topic as enabling the reader to use themes on their WordPress site.

One of the reviewers objected that the user’s real purpose was not to use themes, but to style their site. I can understand where the criticism comes from. Those of us who favor task orientation in technical communications are quite sensitive to anything that smells of its opposite: feature orientation. We don’t want people to be writing topics on the File Menu, for instance. We want them to focus on things that the reader is trying to do. read more

The Paradox of Help Quality

 Why does help still kind of suck even after so many years?

Tom Johnson asks this poignant question in his post Do We Need a New Approach to Help? Why Are Users So Apathetic Towards Help after 50 Years of Innovation?

Tom provides a great survey of the trends and ideas in help design, starting with John Carroll’s seminal work on minimalism and suggests multiple possible ways forward.

I think there is enormous promise in many of the paths Tom invites us to explore, but at the same time, I am struck by the need to recognize that there is limit to how much help help can be, and a real danger in trying to do too much. read more

Why simplicity is more important than functionality in content navigation

Findability is a filtering problem. There is a whole whack of stuff on the Web. To find what you want, you have to filter it. So if you can provide your visitors with a more sophisticated filter, such as a faceted navigation or a taxonomy-based browsing experience, they will have more success finding stuff, right?

Not necessarily, no.

Web Organization is not Like Book Organization

One of the most difficult aspects of moving content to the Web is that webs are not organized like other things — books in particular. And the difference is not small. It is not that web organization is somewhat different from book organization. It is so different that you can’t even look at web organization the way you look at book organization.

And that may be the biggest problem in moving content to the Web. We are used to being able to look at the organization of our content in a particular way, from the top down, and that does not work on the Web. That makes the difference very difficult to get used to. read more

Write for people who actually read documentation

One of the biggest mistakes we make in technical communication is trying to write for every user.

Sacrilege, I know, but hear me out. Many users don’t read documentation. They don’t not read documentation because the documentation is bad, or not written for their level, or uses big words. The don’t read documentation because they are the kind of people who don’t read documentation. It is a fixed part of their character and their outlook on life, and nothing you can do with the documentation will change it. read more