The Nature of Hypertext

Hypertext means more than just text with a bunch of links in it

Hypertext is something of a neglected subject these days. Everyone is talking about the Web, but nobody is talking about the class of thing the Web is: a hypertext environment. But to neglect this essential fact about the nature of the Web is to risk getting your approach to the Web seriously wrong.

Perhaps people associate the term hypertext purely with linking. But I would suggest that there is much more to hypertext than links. Hypertext is about the non-linear traversal of information spaces, and while links were the first tool created for this, there are now four key drivers of hypertext: read more

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

Shibboleths of Technical Communication

A shibboleth is a test which separates friends from enemies, insiders from outsiders, the trustworthy from the suspect.

In medieval England, it was easy to tell the nobility from the peasantry: the nobility spoke French; the peasantry spoke English. This is why our words for meat on the hoof are Anglo-Saxon in origin (cow, sheep, pig) while our words for meat on the plate are French in origin (beef, mutton, pork). A peasant might steal a noble’s horse and cloak, but he could not pass himself off as a nobleman because he could not steal a noble’s tongue. read more

What’s Hiding in Your TOC?

One of the defining characteristics of an Every Page is Page One topic is that it has no sequential or hierarchical relationship to other topics. There are no previous, next, or parent links in an EPPO topic, though there may be many links to topics on related subjects.

One of the objections I often hear from writers is that sometimes they need to create a defined order of topics because that set of topics forms a workflow. The question I ask in return is, if there is a workflow here, shouldn’t you have a topic describing that workflow explicitly? read more

Interest is Fundamental to Communication

The Web continues to invent new places for tech writers to rehash old arguments. Recently I have been seeing a number of reiterations of the old debate about technical knowledge vs. writing skill on various LinkedIn forums, and apparently Techwr-l has recently been debating yet again whether it is easier to teach tech to a writer or writing to an engineer. I am convinced that both sides in these endless debates are missing the point: the key to successful communication isn’t knowledge or writing skill, it’s interest. read more

Want Respect? Get out of Publishing

I recently wrote the following in a comment on Tom Johnson’s blog post What Tools Do Technical Writers Use:

That writers are still expected to do their own publishing strikes me as one of the tragedies of the profession, and a major part of why tech pubs does not get the respect it thinks it deserves in organizations. It is a big part of the reason that so many people still dismiss what tech pubs does as “making it pretty”.

It was not the most deeply considered statement I have ever written, and when I read it over after having posted it, I rather wondered at the sentiment it expressed. Why exactly should engaging in publishing lose you respect? It’s not as if people universally lack respect for publishing. It’s not as if publishing is something akin to pyromania or politics, rightly despised by all. Yes, there is the “making it pretty” thing, but why exactly should the ability to make content pretty lose you respect? People are not generally opposed to pretty. They like pretty. They pay a lot of money for pretty. read more

Tech Comm’s Place in the Choir

All God’s creatures got a place in the choir
Some sing low and some sing higher
Bill Staines

Birds on a wire

A place in the choir

Traditionally, technical manuals have been written as if they were the only source of information on a product. Of course, the manual was never really the only source. There have always been neighbors, friends, colleagues, retailers, user’s groups, and professional associations to learn from as well.  But access to these other sources of information was not universal, and those groups themselves had to learn from somewhere — information had to propagate through the network before it became available to the ordinary user, and the propagation was usually quite slow. It was reasonable, therefore, for users to look on the documentation as their principle source of information, and it was reasonable and necessary for the documentation to be written as if it were the sole source of information on a product. Not any more. read more