The Book

My book, Every Page is Page One: Topic-based Writing for Technical Communication and the Web, is available form XML Press. Here’s an expanded outline of the book:

Preface: In the Context of the Web

Even when content is not on line, the reader is. We don’t go online anymore, we are online all the time. All content is consumed in the context of the Web where Every Page is Page One.

1. Introduction

Readers look for information the way wild animals forage for food — seeking good-enough information that takes the least effort to find and digest. The Web make information foraging easier, and therefore people spend less time struggling with difficult content. They prefer short information snacks, which are best provided by Every Page is Page One topics.

I. Content in the Context of the Web

How readers find and use content is different in the context of the Web.

2. Include it all. Filter it afterward

Why would readers prefer to forage the Web rather than use a well-structured book? The Web has a wider scope than any book and Google returns information faster than a trip to the bookshelf or the library. The Web provides access to a long tail of information that will never find its way into books. The Web provides access to people with experience as well as to experts. The Web supports aggregation and curation of content — the reader does not have to do their research alone. And the Web provides filters to enable the reader to sift and sort all this information to suit their needs.

3. The Distributed Nature of Content on the Web

Creating a website is not like writing a book. The Web works by creating dynamic semantic clusters through search and curation. Your content is distributed across the Web by the different filters that pull in individual pages. People don’t arrive at your site, they arrive at your pages. Every Page is Page One.

4. Information Architecture Top Down

Books are organized from the top down with tables of contents. But tables of contents don’t scale. Faceted navigation can help, but only if the facets make sense to the reader. We have reached the limits of what top-down navigation can do.

5. Information Architecture Bottom Up

A web is organized bottom up. Every page is page one, and every page is a hub linked to other pages by a web of subject affinities. Hierarchies flatten reality. Organizing content from the bottom up allows us to express more complex relationships that are more true to the irregular nature of the real world. Beyond a certain scale, only bottom-up organization is effective.

II. Characteristics of Every Page is Page One Topics

6. What is a Topic?

There are building-block topics, designed to be assembled into something larger, and presentational topics, designed to be read as a unit. We need to clearly understand the difference, which is unfortunately blurred in some current information systems. Every Page is Page One topics are presentational topics that are designed to work out of sequence and out of context.

7. EPPO Topics are Self-contained.

Every Page is Page One topics are self-contained. The are designed not merely to stand alone, but to function alone.

8. EPPO Topics have a Specific and Limited Purpose

Every Page is Page One Topics have a specific and limited purpose. Their purpose is based on serving the reader’s purpose, but is not necessarily identical with it. Topic may serve different purposes for different readers.

9. EPPO Topics Conform to a Type

Every Page is Page One topics conform to type. The type of an EPPO topic is not something generic like concept, task, or reference, but more specific and related to the specific subject matter. The type of an EPPO topic is defined by the information required to fulfill its specific and limited purpose.

10. EPPO Topics Establish their Context

Because a reader can arrive at an Every Page is Page One topic from anywhere, the topic must establish its context.

11. EPPO Topics Assume the Reader is Qualified

Readers come to a topic with very different backgrounds and qualifications. A topic can’t bring every possible reader up to speed without becoming a textbook. A topic should address a qualified reader, and provide unqualified readers with enough context so that they can recognize that they are unqualified, and links to material they can use to qualify themselves.

12. EPPO Topics Stay on One Level

Books change levels at the author’s fiat, prescribing a set curriculum for the reader. Foraging readers working in the context of the Web take charge of their own curriculum. EPPO topics should leave it to the reader to decide when to change levels, and provide suitable links to help them do so.

13. EPPO Topics Link Richly

Every Page is Page One topics are designed to be navigated from the bottom up (even if they are also part of a top-down organization) and to support the reader in steering their own course through the content. To do this, they must link richly along lines of subject affinity.

III. Writing Every Page is Page One Topics

14. Writing Every Page is Page One Topics

A move to Every Page is Page One topics is a move away from the textbook model of documentation to more of a user-assistance model. This is not a move away from educating the reader, however, but a move to a model that has been shown to be more effective in both educating and meeting the short term needs of readers. You should write Every Page is Page One topics the way they are meant to be read: one at a time.

15. Every Page is Page One Topics and the Big Picture

Writers’ biggest concern about moving to topics is how to handle the big picture. Books often express the big picture only through the order of the book or the TOC. In an Every Page is Page One topic set, you create an explicit big picture topic, along with a set of pathfinder topics covering major applications of the technology. Every Page is Page One topics stay on one level, and link to other levels as appropriate, making the big picture available as and when the reader is ready for it.

16. Sequence of Tasks vs. Sequence of Topics

Another common concern writers express is how to handle sequences of tasks in EPPO topics, since EPPO topics have no sequential dependencies. Often books express important workflows only through the sequence of the TOC. In Every Page is Page One, you create explicit workflow topics that link to lower-level task topics as appropriate.

17. EPPO and Minimalism

The Every Page is Page One design pattern draws heavily on John Carroll’s studies that lead to the formulation of minimalism. Every Page is Page One forms an excellent platform for the creation of minimalist documentation, but EPPO is not itself minimalism. Bottom up organization can solve one of the conundrums of minimalism by allowing you to create documentation that is comprehensive while still seeming minimalist to the reader.

18. Structured Writing

Structured writing includes both rhetorically structured and computably structured writing. Every Page is Page One is a form of rhetorically structured writing. Additionally, using a computably structured approach that supports the rhetorical structure you are creating can improve quality and efficiency.

19. Metadata

Metadata is the foundation both of the findablity of content and of it rhetorical and computable structure. But for metadata to be effective, the content must fully merit its metadata. An Every Page is Page One topic is the ideal unit to fully merit useful metadata. The best way to make sure content merits its metadata is to create the metadata first and then write content to conform to it.

20. Linking

Every Page is Page One topics link richly. This chapter outlines a technique to creating and managing links using structured writing and subject affinities.

21. Reuse

Reuse means something different on the Web than it does in paper. Duplicating content is not a good approach for the Web, where it can confuse searches and search engines. On the Web, content reuse has more to do with dynamic semantic clustering and linking.

22. Making the Case for Every Page is Page One

The macro case of Every Page is Page One is the way that working in the context of the Web has changed how people find and use information. Technical communications needs to change or it will lose its audience. The chapter also discusses concrete issues including resource constraints, continuous delivery, content change, content aging, agile, content management, creating PDF and help,the role of technical communications in content marketing, DITA, wikis, and making the case for technical communication on the Web.

23. Afterword: EPPO, but Not for Everything

Is there still a place for books, and book length content? Absolutely, but long-form content plays a more restricted role in the context of the Web.