Docs that are Part of Larger Systems

It is easy to think of documentation as simply the reader’s companion, which they use when they need help with a product or service. But a lot of documentation is more than this, it is part of an industrial or institutional system. Designing and writing documentation to be part of such a system can be quite different from writing stand-alone documentation.

Software documentation vs. everything else

There often seems to be a divide in the technical writing community between those writing software documentation and everyone else. Everyone else includes fields such as manufacturing, medical, and insurance. People working in the “everyone else” camp often complain that much of what is written about technical communications, and many of its tools and so called “best practices” are only looking at software documentation and ignores the needs and practices of “everyone else”. read more

The Reader’s Path Cannot be Made Straight

The straight path. It is an idea with immense psychological appeal to us. Every valley, Isaiah promises, shall be exalted, and every mountain and hill laid low (Isaiah 40:4). As communicators, we naturally want to lay out a straight path for our readers. But the truth is, we lack the power to make the crooked straight and the rough places plain.

The crooked path and the paradox of sensemaking

A crooked path through a forest.

The reader walks a crooked path through a forest of information.
Simon Carey [CC-BY-SA-2.0 (http://creativecommons.org/licenses/by-sa/2.0)], via Wikimedia Commons

In his landmark book, The Nurnberg Funnel, John Carroll described what he called the paradox of sensemaking, which can be roughly summed up as saying that learners cannot make sense of the learning materials because they don’t correspond to their current mental model, which can only really be changed by experience. No documentation can ever work perfectly, therefore, because it can only make perfect sense to someone who already understands what it is saying. read more

Safari Flow and the EPPO-fication of Books

Summary: Safari Flow represents a move to Every Page is Page One navigation for books, but its success is limited when the content is not written in Every Page is Page One style.

At Tom Johnson’s suggestion, I have recently subscribed to Safari Flow. Safari Flow is a new take on the Safari Books Online concept which allows you to rent online access to a large library of technical books. What makes Safari Flow different? Essentially, it takes an Every Page is Page One approach to the navigation of the content it provides. read more

Content is a Utility

Summary: When content is a utility the job of the tech writer is to ensure reliability of supply.

In my earlier post, Content as Furniture, I suggested that while content used to be furniture — something to be acquired selectively and displayed as a prized possession (and a mark of status) — it is rapidly becoming a utility — something we simply expect to be there when we need it, like water or electricity.

The notion that content is becoming a utility has some pretty important consequences that I think are worth discussing. read more