Back in May, I published a preliminary outline of my book, Every Page is Page One: Topic-based Writing for Technical Communications and the Web. I’m grateful to all the people who commented on that outline, and all the people who have commented on the book in draft form. All of those comments have helped me refine and reorganize the book, which is now available from Amazon. Here’s what the current outline looks like:
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.
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.
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.
Every Page is Page One topics link richly. This chapter outlines a technique to creating and managing links using structured writing and subject affinities.
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.
[Edited 2013-10-09 to say the book is now available from Amazon.]