One of the less obvious but more important characteristics of an Every Page is Page One topic is that it stays on one level. As with the other characteristics I have discussed in this series, being standalone, having a specific limited purpose, and establishing its context, staying on one level is not an ideal, but a common feature of millions of page-one topics on the web. What makes this characteristic worth pointing out is that it is something a topic does not share with books.
When an author sets out to write a common topic — a technical article, an encyclopedia entry, a recipe, a blog post, a review, they naturally stay on one level.
Bob DuCharme’s Push, Pull, Next is a technical article that deals with the two different ways you can process an XML document with XSLT. DuCharme approaches his theme from several different angles, including the history of markup processing and the opinions of recognized authorities, as well as practical demonstration of actual code. But in all this, he stays on his chosen level: he is discussing two XML processing modes. He does not delve down into syntax details, nor does he clime to higher or more abstract levels of general programming models.
Similarly, Vlad Samarin’s review of the 2003 – 2008 Subaru Forester sticks to reviewing a particular generation of a car. He does not soar to a general discussion all-wheel drive systems. Tom Johnson’s blog post on Faceted Classification sticks to design issues and does not delve down into implementation issues. The Wikipedia article on Ottawa does not drill down to a detail examination of my house. The Canadian Living recipe for Black Forest Ham and Gruyere Frittata does not switch levels to examine the biology of eggs or the etymology of Black Forest Ham.
Topics stay on one level. Why produce so many exhibits to demonstrate this simple point? Because books don’t stay on one level. Books drill down. This tends to be true of all books, but it is true of technical manuals particularly. The typical organization of a technical manual is the break down the subject into functional areas and devote one chapter to each. Each chapter then begins with the introduction of that functional area and then drills down into finer and finer levels of detail.
Here is an example drawn from a book pulled more or less at random from the programming section of my bookshelf. What follows is a section of the table of content’s from Bruce Eckel’s Thinking in Java:
Constructors and polymorphism
Order of constructor calls
Inheritance and finalize()
Behaviour of polymorphic methods inside constructors
Designing with inheritance
Pure inheritance vs. extension
Downcasting and run-time type identification
Here we see a clear change of levels. We start with the broad concept of polymorphism, drop levels to a more specific implementation discussion of the relationship of constructors and polymorphism, and then drop down again to the detailed consideration of a particular function. Then the chapter pops up a level to talk more abstractly about design issues, and then drops down again to a more detailed discussion of “downcasting and run-time type identification”.
This changing levels is typical of how a chapter in a book is constructed. It is completely different from how an independent topic is constructed. See, for instance, the Wikipedia article on polymorphism which stays on the level of describing the general concept. It does include pseudo-code examples to illustrate what it is saying, but never delves down into the details of syntax.
The books produced by tech pubs departments tend to exhibit this tendency to change levels far more so than third party books like Thinking in Java. This is mostly just due to the fact that they are maintained over multiple generations by multiple authors who must, among other things, accommodate the demands and suggestions of countless developers, product managers, and field staff, all of whom insist that some piece of information that has just come to their attention absolutely must be fitted into the documentation somewhere. No wonder, therefore, that we often find detailed procedures which pause for a paragraph of abstract reflection or background information. Mapping the changes of level in a mature technical manual can produce a graph that looks alarmingly like a chart of the stock market over the last decade.
This is not at all to say that this changing of levels is the wrong way to design a book or a chapter. In many respects it works very well when a book is actually read consecutively and with attention as the author intended it. It is to say that topics and chapters are fundamentally different beasts, and that you cannot make good topics by chopping up books.
All to frequently, companies moving to topics begin their migration by slicing chapters at the section boundaries. But sections of chapters are not structured like topics. Apart from their linear dependence on what has gone before, they are almost always on a downward or upward trajectory through levels of abstraction or generality. As well as lacking the the topic qualities of being standalone, and establishing their context, they lack the essential topic quality of staying on one level.
The fact that topics differ so radically from books in this respect is also one of the hardest things for writers to adapt to when they are asked to switch from writing books to writing topics. When they touch on a detail, their instinct as a book writer is to delve down into it on the spot. Learning to simply mark-up the reference so that it can be linked to another topic at the more detailed level seems to be a very hard adaptation for many writers to make.
What is interesting about this is that if you ask those same writers to write an article about something, in most cases they would very naturally produce an article that stayed on one level. The problem comes when they are asked to write a collection of topics covering a broad subject. It is then that the book writing mode, and the desire to change levels, seems to reassert itself.
Fostering this adaptation to true topic based writing is no simple matter. I’d love to hear from people who have managed to make the transition, or have taught or led others in making it.