In his blog post, Two Competing Help Models: One-Stop Shopping or Specialized Stores?, Tom Johnson explores the dilemma posed by trying to put a company’s help information on the Web using the old tri-pane help paradigm. Do you combine all the help for your product lines into one site with a master TOC, or do you put up multiple small sites with separate TOCs?
Tom shows that there are significant problems with both approaches, but he looks at it only from the top down perspective (which assumes that the reader first finds “the help” and then uses the search and browse mechanisms of the tri-pane help system to find specific pieces of content). Further problems become evident when we consider what is likely the more common case: that the reader Googles for a specific answer and lands not on “the help”, but on a specific page in the help.
To create an example from one of the sources that Tom cites, consider this page: https://docs.palantir.com/gotham/3.9.1.0/ontologymgr/wwhelp/wwhimpl/js/html/wwhelp.htm#href=objEditor.05.4.html
Here the TOC shows where the page is located in the hierarchy of the help system, but what does it do to locate the topic in its subject matter? Very little. In folded form, it is a high-level list of other subjects in the collection, few of which are likely to be relevant to the particular task that brought the user to this page. If the reader has specific questions arising from the people, places, objects, actions, and ideas mentioned in the topic, what does the TOC do to help them find more information on those subjects? Very little. For the most part, pursuing those subjects in the content set would mean starting top-down again at the top level of the TOC.
Every piece of content is rich in subject affinities. That is, the people, places, objects, actions, and ideas mentioned in the piece are connected to those people, places, objects, actions, and ideas, and thus have a connection (an “affinity”) to content that describes those people, places, objects, actions, and ideas. These affinities exist in every piece of content, but in most help content produced today, no means is provided to help the reader follow those affinities.
Yet it is those affinities that actually define the place of a topic in its broader subject area. A traditional book index is an ordered list of the subject affinities in the book. A hypertext link in a Web page is the expression of an affinity between the content in which it occurs and content it links to. Subject affinities anchor a piece of content in time, culture and the reader’s experience. Without subject affinities, it would float meaningless like a piece of nonsense verse: grammatically scannable, but semantically vacuous:
‘Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.
When you seek to locate a piece of content in a collection, it is the subject affinities of the piece that provide the means to relate it to the rest of the collection. “Locating a piece of content in a collection” is another way of saying, “organize a collection of content”, but it comes at it from a different angle. It is a topic-centric way of looking at it, rather than a collection-centric view.
Adopting a topic-centric view of organization is important because as our collections become larger and more dynamic, it becomes more and more difficult to establish and maintain a static organizational frame for an information set, or to navigate a collection using a fixed table of contents.
When the user has landed in your help by way of a Google search, in search of information on a particular problem they are trying to solve, what kinds of additional information are they likely to need if the current topic does not entirely satisfy their needs? It is not information from other general categories of the help system, which is what the TOC provides. It is information related to the subject affinities of the current topic.
Consider this very brief Wikipedia article on the Manicouagan crater in Quebec: http://en.wikipedia.org/wiki/Manicouagan_crater
Here are just a few of the subject affinities it has:
- Geographic coordinates
- Municipal location
- Place in time
- Relationship to historical events (extinctions)
- Scholarship
- Geology
- Astronomy
- Photography from space
The article makes every one of these affinities navigable, and it does so without using a table of contents, except the tiny one for the article itself. (Actually, there is a “Contents” link in the left sidebar of the article. Click on it if you want to see just how useless a TOC is in a really large information set.)
The Manicouagan crater. Photo: Wikimedia Commons
If you want to explore any of the subject affinities of this brief article, you can do so simply by clicking on a link either in the text itself, or in the structured sidebar, which classifies the Manicouagan crater according to the common characteristics of such things, or in the table at the bottom that locates the crater in the fields of Geology and Astronomy.
- Want to find out more about the area of Manicouagan: follow the links.
- Want to find out more about Quebec: follow the links.
- Want to find out more about impact craters: follow the links.
- Want to find out more about the Triassic period: follow the links.
- Want to learn about the study of impact craters: follow the links.
- Want to learn about the spacecraft that took the picture: follow the links.
Every topic in your content set shares multiple subject affinities with all kinds of other topics in your content set. Readers who navigate through your content do so to get more information on a subject they are reading about: they follow subject affinities.
Neither a big TOC nor several small ones provide a good way for them to follow the subject affinities they are interested in. Using one large TOC buries the specific affinities of interest in the vastness of the full information set. Breaking the content up into several small collections will mean some of those subject affinities will stretch between different collections, meaning they won’t occur at all in the TOC of the current collection.
Here’s the bottom line: there is little value in providing a manifest of the entire information set in the context of every individual topic. Readers who want to navigate from any one topic will do so by following the subject affinities of that topic. To enable their navigation, provide them the means to navigate the subject affinities of the topic. Do this through linking, through linked structure, and through linked categorization.
This is a profound change from how we are used to organizing content. Traditionally, there has been one navigational schema for the entire content set, and each piece of content has been fitted into a pre-ordained place in that schema. Navigation is fixed and external to the content. Content hangs off the hierarchical table of contents like ornaments on a Christmas tree.
But in the Web model, each topic is a navigation hub in its own right. If there is an external navigation, it is secondary, and very often compiled from information in the topics themselves. Topics organize themselves by expressing their subject affinities and linking to other topics along the lines of affinity. The navigational view from every node it unique, and specific to that node.
When an information set grows beyond a certain size, there is no other way to make it properly navigable. Seeing everything at once is too overwhelming or general. Artificially segmenting it is too confining Navigation must be specific to the locale you are in, and changes every time you change you locale. This way, you can have an arbitrarily large information set with manageable navigation at every point, and still have the ability to travel very far across it by following were the subject affinities lead.
This may sound like a big leap to make, but lots of stuff on the Web already works like this. There are no shortage of examples to follow. Wikipedia alone provides a rich vein of navigational ideas to mine. The challenge is not to find new ways; the challenge is to stop thinking in terms of 20th century technology. The navigational relics of books and tri-pane help systems are wholly unsuited to a 21st century hypertext world.
Mark,
Great article! I agree, a TOC is a writing contruct representative of printed (paper) books and manuals; I consider is a relic of the past.
We should accept and embrace the paradigm that most content consumers will reach your web content via Google or even a site specific search engine, choose an article from the list, read the first few paragraphs, and then they will choose where to go from there.
In this paradigm, the reader is searching, picking articles from a list, browsing the article, and picking new articles by refining their search and/or hypertext linking to them. At no point are they refering to a “master TOC”.
This is the Google/Wikipedia model of content consumption on the web; and it is why readers prefer web content over traditional form of “help”; e.g. manuals and Call Centers. Simply making Manuals and other documents available on the Web isn’t really giving our customers, the content consumers, what they want. The want the dynamic experience represented by “Every page is page one”.
Thanks for the comment, Dan. I agree on all points.
What do you think of visualizing/designing indexes using a hub-and-spoke affinity model as does the Wordflex app?
This would be a very compelling way to navigate large but finite and interrelated asset collections.
Corry, thanks for the comment. These kinds of cloud/mind map widgets have been around for a long time. They never seem to have caught on. People often find them cool to play with, but they never seem to get put to practical uses in general Web applications.
The reason, I think, is that they are too abstracted. You can certainly map the connotations and denotations of words to make interesting patterns, but subject affinities are not the same as language affinities, and real subject affinities simply have too much content in them to be mappable by these techniques. For the same reason, I think tag clouds are more of a novelty rather than serious navigation tool. They are more interesting than useful.
In short, abstract concept maps simply aren’t very practical as navigation tools to get to the piece of content I want right now because I am interested in a particular subject right now.
Yes – it would be counter-productive to present an index as an index in this manner. I agree. But what about using index data and generating a hub/spoke interface as a form of navigation and exploration. Not as an index, but as a way to explore and access content. It’s front-loading the index, as it were. It beats search and is a very powerful way to browse…
Yes, I think there is something in that. Something I have done in the past is to use topic indexes to generate see also links to topics with similar index entries. Since I always use typed index terms (that is, I don’t just use the term alone, I specify its type — component name, task name, function, config setting, etc.) I can generate links that make the topic itself into a hub connecting it to related topics along multiple lines of subject affinity.
Yes! With all that structured data already in place, it would be just a matter of designing and implementing (no small feat, that) a ‘see also’ navigation thingy. And a matter of finding a client who wants it.
I disagree. I say you are comparing apples to oranges.
Wikipedia is a series of stand-alone articles. You link to Wikipedia’s definitive page on the Manicouagan crater; if an expert in craters accessed Wikipedia with the intent of adding a page about the Manicouagan crater, he would find himself only editing. A person wanting to know about the Manicouagan crater may find everything he wants to knows on this page; he doesn’t need to know more about Quebec to know about the Manicouagan crater.
The documentation for the product I work on is in a hierachy for a reason. You may come into the help looking for information about creating letters. Since creating letters is a subroutine for many modules, if you don’t already know the routine, you’ll be working backwards: from how to create a case letter to how to create a case; from how to create a campaign letter to how to create a campaign. The ToC lets you work backwards that way.
Now, there is a “what is a letter” page – if you land there, you will be working forward, through affinity links: I want a letter, but what kind? How to I create the artifact (case, campaign) that the letter will be attached to? But there is no such thing as a definitive letters page, because so much depends on the workflow.
The hierachy of the help has to mimic (to some extent) that workflow, or you’re into letters “Frankendoc”, as Mark might put it, totally out of context.
Of course, folks are going to say, “I prefer reading Wikipedia than reading most help files,” because it’s one-stop shopping to make you smart about one thing. In most help systems, even with affinity links, the first page is only the beginning of a journey.
Rebecca, thanks for the comment.
It is certainly valid to point out that Wikipedia is a set of independent articles. There is a difference between a general encyclopedia and the documentation for a specific product. The information in a product doc set is more tightly bound together in a number of ways.
But that does not mean that the best organization for a doc set is hierarchical. A doc set can also be written as a tightly integrated collection of Every Page is Page One topics.
You talk about the ability of the TOC to let you work backwards. The ability to work backwards is important in any documentation set, because a user may come to a topic on a particular function and find they need prerequisite content to understand the topic, or prerequisite tasks to complete their task. The user has to work backwards to find those concepts and tasks.
But TOCs are actually a really poor vehicle for working backwards in this way. At best, they can support moving backwards only along a single axis. But different readers may need to move backwards along different axes, looking for different prerequisite concepts or tasks. The TOC, which can only show one backward path, is forced to play favorites and support only one of many possible users needs to move backwards through the subject matter.
True, some products have highly linear workflows, and it is important to express those workflows for users. But as I have commented before in this blog, a TOC is a lousy way to document a workflow. A workflow should be documented in an Every Page is Page One topic in its own right, not buried in the TOC.
And even in products with highly linear workflows, I have yet to see one in which there were no overlaps between operations in different workflows. A single linear TOC can’t represent multiple workflows with common functions correctly.
(This is not to say that in safety critical situations you might not want to train users specifically in the order of each workflow using a linear form of instruction. There are certainly cases where that is appropriate, and material with a fixed linear order is appropriate for those situations.)
“In most help systems, even with affinity links, the first page is only the beginning of a journey.” I agree, but it is a different journey for every reader. It is not (except in certain specific circumstances) the writer’s job to force every reader to follow a curriculum of the writer’s choosing, but to allow the reader to easily navigate the particular journey that they need to follow to get their own particular piece of work done.
Proper linking and link structure have been best practices for a long time, and make it possible for users to find the information they need quickly, without necessarily using the TOC.
But a *logical* hierarchy (TOC) provides another means for users to navigate the information efficiently, so I see them as assets, not liabilities. Search provides a fourth option; a way for the user to group topics by their desired criteria.
Thanks for the comment, Nicky.
I can agree that a *logical* hierarchy can sometimes be an efficient way to navigate information. But I would suggest that it is very rare to find a single *logical* hierarchy that * logically* encompasses an entire information set.
Hierarchies become less logical and more arbitrary the larger they become. Look at any large TOC, and arbitrariness, not logic is the prevailing feature. Hierarchies simply don’t scale.
And, because every piece of content has multiple subject affinities, each of which is logically valid in its own right, it follows that if *logical* hierarchies are useful for navigating a subject affinity, then any information set of any size would have a place for many *logical* hierarchies as navigation devices, and that while none of those hierarchies would be likely to encompass the entire information set, many topics in the information set would occur in more than one hierarchy.
In fact, the Manicouagan crater article illustrates just this. In the subject area maps at the end of the article it places the Manicouagan crater within the separate but intersecting hierarchies of geology and astronomy.
So by all means, let us add logical hierarchies to our arsenal of navigational tools for expressing and navigating the subject affinities of our content. But a single TOC of the whole simply isn’t either effective or logical for this purpose.
Classification is a central issue here. When we develop standalone topics, or EPPO pages, we must develop a principle to know what topics to create.
Facet taxonomies used to both identify and classify topics provide a way to help the user judge the relevance of a found topic. The classification scheme and any selection done in for example a faceted navigation system helps the user to get the context in which a topic shall be interpreted. A badly designed TOC is not helping the user pick up the context.
More about this has been described here: http://www.excosoft.se/index.php/about-us/blog/item/13-how-is-a-topic-signaling-its-content?
Carl, thanks for the comment and for the link.
I agree that classification can be a useful tool. But I don’t regard it as the central issue. The attempt to create a single broad classification schema for content is simply creating a TOC under another name.
I have had this argument with Jonatan Lundin a number of times, and I always come back to the same point. Classification is useful for navigation only insofar as the reader is already familiar with the classification schema. Most readers are not familiar and not interested in becoming familiar. They are not looking to establish content in its logical place in a general classification schema; they are looking to get a specific answer to a specific question and they want a link to a specific topic that answers that question.
That is the broader point I am making in this post. Topics do not fit in one place in one grand classification. They exist at the intersections points of multiple lines of subject affinity. The secret to successful web navigation is not to guide the reader into a single classification scheme, but to allow them to travel at will along any of the lines of subject affinity that interest them in the present moment.
I agree with Rebecca, knowledge flow and workflow should be related. As I mentioned, when we can anticipate the context, we can order the content for the reader.
But too often the writer only imagines the initial use of content, to train on a new activity (how to do something or how to use something), and this is when the content will be consumed sequentially. For that, a TOC can act as a sort of syllabus or outline of everything that needs to be learned to be proficient.
We also have to realize that the content will be referenced many times after that (if it is any good anyway), when the user can’t remember a detail or runs into a problem. Important details (e.g. a table of codes to type in) are often embedded deep within this content; and the detail is often too much information or used too infrequently to be memorized (not to mention that it may change from time to time). Most TOCs aren’t very useful, or user friendly, when the user wants to recall a specific piece of information, and access the content in a non-sequential manner; they already know what comes before and after, but they just need this one piece of information in order to keep working, and they don’t want spend very much time finding and using that information.
Another major use of content is for research; trying to learn more about something in order to make a decision. In this situation, it is almost impossible for us to imagine the context within which the reader is making this decision; or what that person’s decision making process is (often as unique as the person). So, we need to allow the user to explore the content in their own sequence, based first on what interests them when they start the search, and what catches their interest as they read the content.
I found a good article that can sum up some of these ideas for technical writers:
https://resources.learningtree.com/details.aspx?dl=technical.pdf
Content needs to be broken down into usable “nuggets”; with each nugget indicating the most common flow of steps before and after, maybe some sort of embedded TOC; but we also must realize that we can’t anticipate all scenarios where the content could be used, and therefore the content will be used in sequences that the author did not imagine.
And, there may not be a “one-size-fits-all” format of content. Content for training, or for reference, or for research, may need to be published in different forms and formats, which can be tricky when you are trying to keep all the forms accurate and in-sync. This will take extra work by authors, editors, and the publishers; but you can get great value and leverage from these extra efforts when you consider the time and occurrences of creating content vs. the number of uses and time saved when the content is useful and usable; an n=1 vs. n=many scenario.
Thanks for the comment, Dan.
One of the ways in which writers often mislead themselves is they believe that the reader can only learn by reading, and that they are willing to learn by reading. In fact, as Carroll showed long ago, most adults don’t and won’t learn that way.
Be say we are supposed to begin by studying the reader, but we end by blaming the reader for bahaving badly (RTFM!).
This is not to say that there are no cases where linear study occurs. Regulated occupations often require a very specific and linear course of study to qualify for each level of advancement, and people are only allowed to touch the machinery after they are completed that study and demonstrated their mastery. For this purpose, you need a book: a curriculum designed by the writer and imposed on the reader.
Outside of this, it pretty much just does not work. Readers just refuse to cooperate with the program.
Even within regulated professions, however, the prescribed curriculum seldom encompasses all the available content. There are generally large amounts of supplementary and reference content to which random access is the norm and a TOC is not a useful navigation method.
So yes, I too agree with Rebecca that there are cases where the book, the single prescribed curriculum, is appropriate. The just don’t represent the generality of tech comm use or practice.
And, there may not be a “one-size-fits-all” format of content.
I believe this to be the central windmill we’re fighting against.
At my former employer I had the luck to have direct access to customer feedback on my documentations. This had been very helpful in creating much better docs, but also pointed clearly out that there is no “best practice” for any given group of customers.
You can only try to cater to the largest subgroup of them, but even there you’ll find that some understand a certain part, while others don’t.
In a perfect world, we would be creating a set of documentation for every single subgroup of readers, with rich linking to their preferred interests and navigation based on their habits. But nobody is gonna pay for this. And unless we’re able to produce consistent but individual documentation by automated means, we’ll have to stick to one form of presentation.
This is why I like to split my documentation into four mayor parts: Beginners guide, most common uses, the whole thing in references and a rich glossary.
The navigational system for the first part is clearly a TOC, as the information is lined up sequentially, the second part is more of an EPPO style but still held together by a thematic TOC, the third and fourth parts are self-contained EPPO topics that are ordered loosely by what I think is a good order for the target audience but use rich linking between the individual topics.
This works out surprisingly good, as most users quickly get a grasp of how they can use the doc. Beginners read them page by page with an increasing learning curve towards the referential part. Advanced users usually skip the first part and use the most common uses like a quick reference. Experienced users pick the third part to find references on detailed information and nearly all of them use the glossary at one point or the other.
For one product, I could drop the service calls by nearly 60% by reworking the old manual this way.
Long story short, divide your content and use a navigation tailored to it.
I think Alex gives some very practical advice and some good, specific ideas. He has tried to address the users changing needs for content as they progress to higher levels of knowledge, understanding, and skill.
This is a major step forward from the manuals of old that were (and sometimes still are) written as an “Installation, Operation, and Troubleshooting Manual”.
Alex,
I would like to rework one of our Manuals in a similar fashion; do you have any content structured like this that is in a public domain? Maybe I could get a link to it?
I don’t know how good your German is Dan 🙂
But here’s a link to one of my first attempts on such a structure, I made some years ago: http://www.pearl.de/pdocs/PX8569_11_95037.pdf
Still missing in this document is the part for the most common use cases, as I didn’t know about the severity of the impact on this at that time.
But it was illustrated with abstract use case examples already.
Customer feedback was quite positive, except for some people missing more detailed information on common use case scenarios.
Alex, thanks for the comment.
I agree that user needs are diverse, and you can’t create one grand organization of content that serves them all equally well. Different users’ interests lie along different subject affinities. That is why we need to allow navigation along all the significant subject affinities in our content.
You say:
If we provide rich linking, we don’t have to provide a set of documentation for every single subgroup. We provide one set of documentation for all subgroups and provide navigation that serves all subgroups equally well. By writing Every Page is Page One topics and providing rich navigation along all significant axes of subject affinity, we allow every subgroup and every individual to find their own way through the documentation.
And the fact is, this is what they prefer to do anyway. When we try to provide an ideal navigation for one group, even that group ignores us and dives headlong into the content, making their own way. (Our general confidence that the given organization of content will meet our need is so low we don’t even bother to look at it most of the time.)
We can’t get it right for every group, and they wouldn’t recognize it even if we did. What we can do (and can do affordable) is to make their headlong plunge into and through the content work really well by making sure that every page works as page one, and that every page links effectively along all of its subject affinities.
By this comment I have not only been talking about structural presentation of content, I’ve also been referring to terminology, complexity of used language, style and many more aspects that influence the understandability of a documentation.
Just to name a few groups with very special requirements for a documentation, which we cannot cater for (or only in rare occasions): older people, children, illiterates, blind people, mentally handicapped people, and so on.
And these are only the ones, that are obvious.
So, by producing just an average manual, we neglected the needs of already quite a number of people.
If the target group is unknown or very large (lets say you’re writing a manual for a TV screen), you’ll have a massive difference in subject knowledge.
You see where this is going…
But, the perfect world would cater them all.
And as we live in a world where documentation follows the rule “get it done, in x weeks(days, months), for that budget, in those types of media”, we will not (yet) be able to do anything but cater for larger user groups.
Thanks for the clarification, Alex. A couple of points in response:
Documentation should be written for the kinds of people who read documentation. Documentation is not the only way to get information about a product. Asking other people (who may have read the documentation) is a common approach. A lot of the groups you mention are very unlikely to be the kind of people who read documentation. There is no point in writing for them because they will not read the doc, no matter how well it has been designed for them. They are no the kind of people who read documentation. That is a set feature of their character that you will have no opportunity to change.
Among those groups there are doubtless some people who are the kind of people who read documentation, but they, as part of the distinct sub-culture of documentation-reading people, will be far closer to the “ideal” reader than their peers in their cohort.
That said, there is indeed within the subculture of documentation readers a considerable variety in their ability to deal with terminology, complexity, etc. If you are writing a book, you generally try to keep that book on a single level regarding terminology, complexity, etc. You pitch the entire book at readers of a certain level or with a certain background. Such a book becomes increasingly frustrating as a reader diverges from the level for which the book was written.
But in a collection of Every Page is Page One topics, there is no restriction that says every topic in the set must be written for the same audience. Indeed, one of the principles I give for writing Every Page is Page One topics is that each individual topic should be written for a user qualified to read its subject matter. In other words, you don’t qualify a reader for the entire collection, you qualify the reader for each topic separately. Different topics in the topic set may be written for readers at different levels, and readers can use lower level topics to qualify themselves to read higher level topics.
So, while it isn’t possible to write a single doc set to cover the whole human race, I think it is possible to write a set of EPPO topics that cover the needs of the actual documentation-reading subset of the user base of a particular product, and to have each topic address the reader at a level appropriate the the task they are trying to perform.
@Mark Baker
I am still seriously confused about the point being made in this article. Here are some of my problems.
First, I see no conflict between “every page is page one” and a ToC, or for that matter a paper book. Even on paper each topic should treat information related to the topic comprehensively.
Second, a Google search is itself a ToC, except that it is arrived at in a different way than a writer generated ToC. The Goolge ToC captures things like popularity, semantic relevance, semantic weight, links to and links from, etc. The Google ToC is generated by an algorithm. How relevant that algotrithm is to any particular user is problematic, especially in reference to technical information. Ever since Google started “tuning” search results to my search history, the tool has become less and less useful.
Third, a logical writer generated ToC will itself affect search tools: links count in the weighting.
Fourth if a book is published to the web, each topic can hardly help being a naviagtion hub on its own: it has a place in a logical structure, links based on subject affinities ae easily added with the right SW tools, BUT affinities within the logical structure obviously have to be higher than others, etc.
Anyway, there seems to be a strong feeling here that the book is dead and not adaptable to web presentation. But, if you map out a set of subjet affinities in web space, look at the progress of a user through those links, you ALWAYS end up with a path that can be represented as a linear progression, just like a book, but maybe a more “spontaneous book”. This has to be true because the human agent can only look at one thing at a time.
I fail to see the advantage of presenting the “book” and the “ToC” as a problem on the web versus affinity links. Why try to force an either / or decision: book and ToC versus affinity linking. Why not promote both and present affinity links as a lost opportunity? I like affinity links. I like the idea of every page as page one. Perhaps I’m a little dim on this topic, but still fail to see why this is being presented as a conflict.
@Dan Shulte
Your comment “I agree, a TOC is a writing contruct representative of printed (paper) books and manuals; I consider is a relic of the past.” is a bit misleading. If you a writing a procedure for welding a gas tank, you had better have a clear ToC or the equivalent to try and ensure the end user follows each step in a logical sequence. Each major operation must also have a check to ensure that the previous procedure was completed properly. And, even if I admit that “a TOC is a writing contruct representative of printed (paper) books and manuals” some mechanics will want to print the end-to-end procedure — and it better have a ToC or a checklist equivalent. If the ToC is a relic of the past, I don’t see any easy way of getting around it, without blowing things up, or failing to stop the plane, or rupturing pipes in the refinery, etc. etc. etc.
Peter, thanks for the detailed and thoughtful comment. I’ll try to address each of your points in turn.
First, I see no conflict either. You can assign a presumed reading order to a set of EPPO topics and print them in a book with a TOC. In my previous post (/2013/02/04/what-is-your-primary-media/) I make the point that you need to choose which media you design for primarily, and then accommodate the content designed for the primary media as well as you can for the secondary media. Much tech comm is still designed as if paper were the primary media and then adapted (badly) to the Web. EPPO is about designing primarily for the web, and then adapting if necessary for print. And it turns out that adapting EPPO for print yields a much better book than adapting a book for the web yields web pages.
Second, if we call a Google search a TOC, we are broadening the definition of a TOC considerably. A traditional TOC has two principle features: it is comprehensive, and it describes a presumed reading order. A Google search does not create a TOC in this sense. My criticism of the TOC as a means of organizing help is specifically aimed at the comprehensive/ordered TOC used when tri-pane help is pushed to the Web.
A writer-generated table of references along one or more lines of subject affinities would not be a TOC as I am using the term. While I think more highly of Google than you seem to do, I agree that there are other useful, directed, human generated forms of navigation that greatly increase the usability of content. Typical tri-pane help contains none of these. I am arguing for including more of these, including rich inline linking, and dropping the comprehensive/ordered TOC, which is ineffective on the Web.
Third, yes, writer generated links affect search. They should be the subject affinity based links I am talking about, which better reflect the true nature of the content than a TOC.
Forth, if a book is published to the web using current techniques, the only links it tends to have are back, next, up, home, etc. Those don’t aid navigation except navigation through the book.
Why choose? Why not have the TOC and all the affinity links? Clutter, for one thing. TOCs take up a lot of real estate. Misdirection, for another. TOCs make it look like the content is a book when it isn’t. By all means put the TOC into the PDF version that you generate as the secondary media. But it does not belong on the Web.
On the general theme of the everything should be optimzed for the web, my math/physics son made an interesting comment last year. He said the web was great for looking things up, but if you wanted to learn something you have to buy a textbook (or the equivalent online information product).
I thought it interesting because math and physics textbooks are a great example of every page is page one (narrow topic definition, all necessary information is present, etc.)
But, every topic has to be placed in a larger logical context or it is not “learnable”. That logical context has to be created by a writer who defines learning objectives and steps in the learning process in a (mostly) linear book-like fashion.
What does every page is page one say about the textbook and my son’s contrast between textbooks and the web?
Peter, I agree with your son. There is still a place for books, and an important place.
Every Page is Page One says that if you are writing for the Web, you should optimize for the Web. Not everything belongs on the Web. If something should truly be a book (because of the nature of the reader’s need, not the author’s preference or habit) then you should write a book.
When you are forced to write for both, though, it is very clear that designing for the book and then adapting the content to the Web works abysmally. Writing in EPPO topics and adapting them to paper works fairly well, though not necessarily as well as writing as a book.
For the majority of tech comm, the user demand is for quick answers in response to individual questions and problems, and EPPO on the Web is clearly the best format to meet that need.
But there is still a place, including in tech comm, for sustained study, and for the reader’s surrender to the author’s intended curriculum, and for that the book remains the appropriate medium, and paper or an ebook the appropriate vehicle.
My argument is always for an reversal or our priorities: web first, book second, not the complete elimination of the book.
Your blogpost helped me to get rid of an ideology that said, no links within the text to other pages of the help! It originated in the days of DITA 1.1. Now we have the standard DITA 1.2 with keys and keyref. Your article was a wake-up call to use this technology at last. Thank you.
Pingback: Every Page Is Page One » Ditalog