In Praise of Long-form Content

Yesterday I wrapped up work on my new book on Structured Writing and delivered it to the publisher. There will be more work to do, of course, after the pre-publication review process is complete, but in a broad sense, the book is done. That is, the arc of the book is complete.

Good books have an arc. Finding that arc is one of the great joys of long-form writing. Of course, this blog is about short form writing — about Every Page is Page One topics that serve a single discrete purpose for the reader. But in a sense even a book should fit that mold — should serve a single discrete purpose for the reader. The whole should be more than the sum of the parts. There should be an arc, something the book says that is more than an accumulation of details, and that allows the reader to see the details in a new light — and to act differently and, hopefully, more successfully, in that new light. read more

7 Keys to the Discipline of Linking

Following my recent STC Webinar on Every Page is Page One, an attendee wrote to ask about the discipline of linking. Unfortunately, that email mysteriously vanished from my inbox before I could answer personally, so, whoever asked, I hope you see the answer here.

Linking is important to Every Page is Page One and to a bottom-up information architecture. When readers can enter your content at any individual page, links are what orient them in the larger content set and what keep them in your content rather than sending them back to their search engine. read more

Search ranking and bottom-up architecture

Does a bottom-up information architecture improve search ranking? This is another in a series responding to questions from my TC Dojo series on Bottom-up Information Architecture. I have several questions from the second session on writing, but I’m still working off the backlog of questions from the first session on organization. (Because we are moving and renovating is why.)

Q: How does Mr. Baker contend to navigate Google’s “filter bubble” and the highly competitive market for search result display order? read more

Bottom-Up Architecture Q and A: Organizing the Site

Once the reader reaches an Every Page is Page One page, does it still matter if the site is well organized? It depends on what you mean by “organized”.

This is another in the series of post dealing with questions from my TC Dojo Webinar on bottom-up information architecture.

Q: I understand that the site is not online, but it is the pages…however, you still need to have a site, right? …once a user gets to a page, don’t you want them to be in an organized site?

A: Absolutely, we always want our content to be well organized. But electronic media, and the Web in particular, have profoundly changed what it means to be organized. read more

Bottom-Up Information Architecture Q and A – Part 1

I got a number of really good questions following my TC Dojo session on Bottom-up Information Architecture (below).

I want to address the questions in a little more depth than was possible in the webinar.

Q: I’ve attended multiple Every Page is Page One webinars. They get bogged down in theory but never explain what tasks working technical communicators should perform. “Books may be bad” but at least people know what steps to take to make one. What tasks and steps shall one perform to implement this wondrous new content architecture? read more

Topic Patterns vs. Topic Types

One of the principles of Every Page is Page One information design is that an EPPO topic conforms to a type. But I have come to think that that formulation is not quite right. It should really be, an Every Page is Page One topic conforms to a topic pattern.

The difference between type and pattern

What is the difference between a topic type and a topic pattern? In structured writing terms, a topic type, or, more generally, a document type, is a formal set of rules about the structure of a topic which is capable of being expressed by a schema. In most cases, that means an XML schema or something similar. This usage is consistent with the use of the word “type” in other computing applications. A type is a data definition. read more

Subject First; Context Afterward

In communication, they say, context is everything. Actually, “everything” consists of context and subject. Useful information is subject in context. The question is, which comes first: context or subject?

In the book era, the content search pattern was: context first, subject afterwards. That is, suppose you deliver three different products and have released three different versions of the product. Assuming only a single manual per product/version that meant you had 9 manuals, each with a page on feature X. 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 (], 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

Design for Wayfinding

Much of the time we spend with technical documentation is concerned with wayfinding. That is, it is not about performing the actual operation, but about finding which operation to perform, and finding the piece of content that describes the operation in a form that we can understand.

Note that there are two distinct components to this description of wayfinding. It is tempting to think of wayfinding purely in terms of finding the right piece of content. But simple content wayfinding really applies only in cases where the user it thumbing through a well known and well used reference work. That is, in cases where we know exactly what we are looking for, and merely have to locate an individual data point. read more