Stop linking. Embed instead.

There's an aphorism that is especially apt to technical writing; "When the only tool you have is a hammer, everything looks like a nail." For evidence, look at almost any HTML-based help systems. The basic tool of HTML is a hyperlink, and many help systems have more links than they do actual information. It's understandable, from an authoring perspective hyperlinks are easy to create (but usually bothersome to maintain) and just like the staff in Home Depot, when you send someone off to look elsewhere for their answer, you've relieved yourself of any obligation to provide actual assistance.

Striking a balance between including redundant information in help pages, excessively linking between pages, and including "complete" navigation is a very tricky thing. (You can read about one approach at the O'Reilly MacDevCenter.) But really, the question of "to link or not to link" is archaic. Modern HTML techniques allow you to embed information that only appears when the user wants to see it, without taking them to a new page. While I have concerns about the excessive hunting-and-clicking this could require, it's almost certainly better than the cyclical link-fest that often results once you go down the slippery slope of cross-linking all related topics.

For a clean and interesting demonstration of the embedded approach see Nathan Matias' Writing Tinderbox Stretchtext Documents. You'll find links on this single-page that reveal extended content, show marginalia, and insert additional reference material. Authoring a complete help system using this approach would be challenging with today's tools, but the result would certainly be quite different than what we're used to seeing today. And I'm thinking it would be better, too.

Posted: November 25, 2006 link to this item, Tweet this item, respond to this item