NOTE: There is a new book outline posted here: Revised Outline: Every Page is Page One. Comments on this version of the outline are closed. Thanks to all who commented.
As I announced a while back, I am working on a book called Every Page is Page One: Topic-based Writing for Technical Communication and the Web. The book is in pretty good shape at this point, so I wanted to share the outline with you to see if you have any feedback that I can incorporate before the last i is dotted and the last t is crossed.
As an added incentive, XML Press will present a free copy to one person, selected at random, who comments on this post.
Here’s the outline:
Every Page is Page One: Topic-based Writing for Technical Communication and the Web
Part I: Topics and the Web
The Web is a hypertext medium. It has a million paths, but no starting place. In such an environment, every page is naturally page one. Why would people prefer to seek information in something so large and unruly as the Web when they have been provided with a nice orderly manual? And what is a topic in a hypertext environment, and how does it differ from a topic in a book? Part I looks at how the Web has changed the way people seek information, and what it means for those of us who create content.
Include it all. Filter it afterward.
In the book world, filtering information was expensive and people preferred to let authors and publishers do it for them. The Web is a giant information filter that lets readers filter content for themselves. It gives readers effective access to information on their specific issue. That is why people would rather search the Web than read the manual.
What is a topic?
The word topic is used in technical communication to mean both a independent unit of information, and a building block from which larger information units are built. You might build the first kind of topic from a number of the second kind, but it is important to know which you are talking about at all times.
Part II: Characteristics of Every Page is Page One topics
What does an Every Page is Page One topic look like? How do I write one? How do I know if I’ve done it correctly? Part II covers the purpose and anatomy of Every Page is Page One Topics.
EPPO Topics are Self-contained
An Every Page is Page One topic is self contained. It does not rely on a previous topic or presuppose a next topic. But while it is self contained, it is not all sufficient. Every Page is Page One topics depend on the web in which they are located.
EPPO Topics have a Specific and Limited Purpose
An Every Page is Page One topic serves a specific and limited purpose for the reader. Its purpose is not to contain facts, but to serve reader’s needs within well defined boundaries.
EPPO Topics Conform to a Type
Every Page is Page One topics that serve a well define purpose also seem, quite naturally, to conform to a definite type. These types are not invented; they arise because to serve a certain kind of purpose, a topic must contain certain kinds of information. Those information requirements define a topic type.
EPPO Topics Establish their Context
Because a reader can arrive at an Every Page is Page One topic from anywhere, a good topic must establish its context. Information without context is meaningless, so topics are most efficient when they establish their context quickly and accurately. Context does not mean the place of a topic in an information set or a table of contents but in the real world of its subject matter.
EPPO Topics Assume the Reader is Qualified
A topic can only stick to its specific and limited purpose, and conform to its type, if it is written on the assumption that the reader is qualified to read it. Readers who are not qualified should be directed to other topics that they can use to get up to speed.
EPPO Topics Stay on One Level
Books often change levels many times, from abstract heights to the most intricate technical details. Changing levels is a necessary part of the study of any subject. In a book, the author decides when the reader should change levels. On the Web, the reader decides for themselves. A good Every Page is Page One topic should stay on one level, while facilitating the reader’s desire to change levels, should it occur.
EPPO Topics Are the Narrative Minim
Information is meaningless without context. Two things can establish the context of statements: narratives and structured references. Narratives can place information into a decision making context, so topics are about decision support. The smallest effective topic on any subject is that one that enables the reader to decide and act effectively on a single issue. That is the narrative minim.
EPPO Topics Link Richly
Because Every Page is Page One topics permit the reader to form their own curriculum, to include everything and filter it afterwards, and because they assume the reader is qualified, and stick to one level, they need to provide the reader with many options about where to go and what content to consult next. Good Every Page is Page One topics link along all lines of subject affinity in the text.
Part III: Organizing Every Page is Page One topics
While every page is page one in a hypertext environment, the difference between hypertext and a miscellaneous jumble is the relationships between pages. Without organization, readers can become hopelessly lost in a sea of topics. But Web organization is not like book organization. Part III looks at the differences, and how you can create both Web organization and book organization for your Every Page is Page One topics.
Organizing Topic Sets
There are three ways of organizing topic sets: the book way, the database way, and the Web way. All three methods work with Every Page is Page One topics, though the book way is the least desirable.
Every Page is Page One Topics and the Big Picture
How do your cover the big picture in an Every Page is Page One information set? In the book world, the big picture was often implied by the organization of the book, but never stated. When books are split into topics there is no big picture topic and the big picture is lost. In an Every Page is Page One topic set, the big picture should be covered explicitly in a topic, and other topics should link to it wherever the reader might be curious about the big picture.
Sequence of Tasks vs. Sequence of Topics
Writers often worry about how to document a long sequence of tasks using topics. The answer is essentially the same as for the big picture. If there is a workflow that sequences many tasks, write a topic to cover that workflow. On a smaller scale, don’t fall into the trap of supposing that one task topic must contain only one procedure. It is a task topic, not a procedure topic, and it should contain as many procedures as are necessary to complete the task.
EPPO and References
Every Page is Page One is about recognizing that readers don’t follow a curriculum defined by the author. They access content randomly as they need it. The best way to support random access to content is actually not through topics, but through structured references. Topics are required where you need a narrative to frame the business decisions that impact a task, but for every other purpose, a structured reference is preferable. An EPPO content strategy builds on a foundation of structured reference material.
Part IV: From books to Every Page is Page One topics
Once you have learned how to write and organize Every Page is Page One topics, the next problem you will probably face is the mass of book-like legacy material you have to deal with. As we have learned, you can’t make Every Page is Page One topics by mechanically separating books at section breaks. Part IV looks at how you deal with migrating your existing content to Every Page is Page One topics.
From Textbooks to User Assistance
There have long been two model of technical communication: the textbooks model (focusing on education) and the user assistance model (focusing on immediate aid in the course of the workday). As Minimalism showed us, the user assistance model actually fits better with the way adults learn. The Web, by assuring people of instant access to information further tips user’s preferences toward the user assistance model. In moving from books to EPPO, it is important to bear in mind that you are also moving from a textbook model to a user assistance model.
From Books to Every Page is Page One
If you have a lot of legacy content in book form, you need to deal with it during your move to EPPO. This chapter looks at how to go about dealing with your legacy book content.
From one-time to continuous publication
In the paper world, content development generally stopped before the product was released. But useful information about your product, particularly the kind of task and troubleshooting information that users need most, continues to be created long after the product is in the market. Web users expect content to be always up to date and current. You can no longer simply publish a manual at release time and forget about it. You will be adding information to your content set throughout the product’s life. You will need to adjust your workflow and procedures accordingly.
Part V: Common concerns
Do I have to choose between EPPO topic types and Concept, Task, and Reference? What about reuse, style, or minimalism. How does EPPO fit with content strategy? What about metadata? And is there still a place for books? Part V looks at how the Every Page is Page One approach fits with common tech comm and content strategy concerns.
Task, Concept, and Reference Reconsidered
DITA has cemented the trio of concept, task, and reference as the three main topic types in technical communication. But EPPO topics require much more specific types to ensure they meet their defined purpose. This chapter will look at the differences.
Reduce Reuse Recycle
Reuse is the hot topic in technical communication today. EPPO is not a reuse theory in itself, and you can produce EPPO topics using reuse strategies if you want to. But reuse in an EPPO environment on the Web can be quite different from reuse across multiple discrete book-like information products. This chapter looks at the differences.
Style and consistency
Should every topic sound like it was written by the same person? Some companies want all their communications to sound alike, but that can reduce customer identification. Other companies recognize that customers respond better to distinct human voices. Certain reuse strategies can put you in a box style-wise. EPPO gives you options.
EPPO and Minimalism
In many ways, minimalism was developed before there was an information medium that really fit the model of user behavior on which minimalism was based. Trying to accommodate the self-directed behavior of users in a linear book has always involved some form of compromise. EPPO was made for minimalism, and minimalism for EPPO.
What About Videos?
Video is a naturally Every Page is Page One medium. You will very rarely find a video that is produced as part of a defined sequence of videos. As such, all the characteristics of a good written EPPO topic also apply to a good video EPPO topic.
Every Page is Page One as Content Strategy
One of the central challenges of content strategy is to maintain the integrity of an information set that is in constant flux, with new items being added constantly by many authors, and older items being removed. All this has to happen in real time with a minimum of overhead and disruption. Every Page is Page One provide the ideally adaptive content model that makes these aspects of content strategy easier to manage.
Is there is Still a Place for Books?
Is there still a place for books in an EPPO world? Yes. (There had better be of I’m wasting my time writing this one!) But the role has changed. Many functions previously performed by the book are now better performed by the Web, and the role of the book as the debut medium for ideas may be over, in favor of a role as a means of summation and recapitulation.)
Part VI: Implementation notes
How do you adapt your current tools and processes to produce Every Page is Page One topics and present them on the Web, and, if necessary, on paper? Part VI looks at tool and process issues involved in the move to Every Page is Page One topics.
This chapter will review the tools typically used in technical communication and Web development, including DITA, and look at how they can be adapted to create EPPO content. It will also suggest that some common Web development tools might now be good candidates for technical communication as well.
Linking plays a major role in writing and organizing EPPO topics. This chapter will look at some techniques for creating and managing links along the lines of subject affinity, and for doing so efficiently.
Metadata plays a vital role not just in finding content, but also in creating and managing it. This chapter will look at the role of metadata in creating, managing, and organizing EPPO topics.
This chapter will look at the workflow issues involved in the writing and publishing of EPPO topics, and at some of the workflow issues that are made easier to deal with in an EPPO system.
This chapter will look at the publishing issues for EPPO topics.
Appendix: List of Every Page is Page One Documentation Samples
A list of EPPO topic sets currently available on the Web, with commentary.
That’s it. What do you think? What am I missing? I need your help to make this book as good as it can be. Please chime in in the comments! Thanks.