Frankenbooks Must Die: A Rant

I was astonished at Sarah Maddox’s statement, in her guest post Why don’t technical writers use wikis — or do they? on I’d Rather be Writing, that wikis are not good at topic-based writing. Huh? Wikis are all about topic-based writing. In fact, it is the only type of writing they really support.

What’s wrong here? It certainly isn’t that Sarah does not understand wikis. If you want to know about using wikis in technical documentation, Sarah is the first person you want to talk to. If anyone knows wikis, it’s Sarah. She’s even written a book on the subject. What’s wrong, apparently, is that the term “topic-based writing” seems to have been corrupted or co-opted and robbed of its proper meaning. This is serious, and it needs to be fixed.

Now, I’m not usually one for mandating what words mean. My general posture on matters of vocabulary is that language is a democracy and words mean what they are understood to mean and that is that. But there are times when important distinctions are being obscured, whether deliberately or through lack of perspective, and one has to issue a call for a more precise usage, and more attention to the distinction.

“Topic”, in tech comm, is commonly used to mean two quite distinct things. The first is: a small piece of content designed to cover one thing (that is, to describe one topic). This is generally what we mean when we talk about a help topic, for instance. This is topic-based writing as a style of information design. The second is: any small piece of content that can be stored separately and then combined with other pieces to form some larger work. This is topic-based writing as a compositional mechanism.

The DITA community uses the term topic in both senses. Its formal definition of a topic is a piece of content that can stand alone, but it also uses the word topic to describe any unit that content can be broken down into, meaning that a DITA topic file can contain as little as a sentence or a title. There is, of course, some ambiguity about what “standalone” could mean in this context, which is something I have written about before, but the reference to a topic as a standalone piece of content seems clearly to be referring to the information design sense of “topic”.

A wiki is all about topics as an information design concept. Wiki’s don’t do long documents. A wiki is a collection of individual related topics. What wiki’s don’t generally support is the composition of wiki topics from smaller reusable fragments of content. If we see wikis as something that don’t do topic-based writing, therefore, this can only mean that the information design sense of the word topic has been largely eclipsed by the compositional mechanism sense of the word, which, in a profession that is moving (however painfully and slowly) from the book to the web, is a pretty serious matter.

I have been writing about the compositional mechanism for close to 20 years now. I gave a paper at SGML 95 entitled “Component Based Information Development” in which I described a process for composing books from components in a database. I have been pretty consistent in the terminology that I have used since then: a chunk of content that is intended to be combined with other chunks is either a “component” if it has a consistent structure and a well defined interface, and a “fragment” if it is just a random piece of text (“chunk” being a more generic term that covers both).

You can use component-based information development as a compositional technique no matter what your information design approach is: you can use components or fragments to construct topics, to construct books, or, as is increasingly the case today, to construct Frankenbooks.

What are Frankenbooks? They are the unhappy result of people being told that they must get away from producing books and move to topic-based authoring but without a proper distinction being made between topic-based writing as an information design approach and topic-based writing as a compositional mechanism. They are the all-encompassing deeply-nested information hierarchies in which all the pieces extracted from an original set of books have been threaded together into one monstrous info-glob.

In a real topic-based information set, Every Page is Page One; in a Frankenbook, no page is page one. A Frankenbook is organized neither for linear reading, nor for random access. No matter where you land in it, you are in the middle of a maze with buttons to move up, down, or sideways, but no means of finding the end of any thread of narrative, great or small. Every page is page 297 and none of them answer your question, or help you find a page that does.

Frankenbooks are the result of basing a business case for process change in tech pubs solely on cost reduction considerations. They are the result of migrating to DITA by sending all your existing manuals out to be automatically converted into DITA topics. (Automatic conversion may be a legitimate tool in an overall migration to true topics, but by itself it does not do the job.)

To be clear, I am not saying that DITA adoption automatically leads to the creation of Frankenbooks. You can use DITA to do proper Every Page is Page One topic-based writing, or to create conventional books, or to create Frankenbooks. The choice is entirely yours. Nevertheless, DITA is often responsible for the creation of Frankenbooks, because, for a tech pubs group with tight deadlines, limited funds, and a load of legacy content, creating Frankenbooks is the path of least resistance.

One of the key design goals of the SPFE architecture (though not one I necessarily lead with in conversation) is to make sure that Frankenbooks are NOT the path of least resistance. You can create genuine books in SPFE, but the path of least resistance is to create Every Page is Page One topics. (It is really easy to create a Frankenbook with a map; it is really difficult to create one with a query.)

Wikis are the same way: Every Page is Page One topics are the path of least resistance in a wiki. I have said before that I am not a fan of wikis, being a structured text guy bred in the bone, but I would a hundred times rather work on an Every Page is Page One wiki than on a Frankenbook DITA system. (Heck, I would rather work on a genuine book-based information set in Frame than on a Frankenbook DITA system, and those who know my feelings on Frame will appreciate that that is saying something.)

This is why it is so important to maintain the phrase “topic-based writing” as something that describes an information design strategy, not merely a compositional mechanism. Minimalism is about writing topics, not Frankenbooks. As I noted recently, the Web does minimalism, and the web generates topics, not Frankenbooks.

There are, alas, people who are creating Frankenbooks in the mistaken belief that their hierarchy is necessary to navigation and findability. The very opposite is true. One must begin by remembering that readers are not looking for topics or content; they are looking for information. The first principle of findability is that whatever is found must provide the information the reader is seeking in a form they can recognize, understand, and trust. Good topics do that. Frankenbooks do not. Providing multi-faceted ways to navigate a collection of Every Page is Page One topics improves findability; building a single monster hierarchy of content fragments does not. It is the first and most pressing business of an information architect to know the difference.

Tragically, there are many tech writers who seem to believe that in creating Frankenbooks they are actually adding value, and thus saving their jobs from being made obsolete by community content. The problem with community content, they assert, is that it is not written in a single tone and voice and arranged in a single organizational structure. I sometimes stumble into Frankenbooks when I am searching for information on the web. They are easy to recognize, and uniformly unhelpful. I just hit the back button and pick the next promising entry in the search results. If tech writers want to show that they can add value beyond what community content provides, they need to learn how to write Every Page is Page One topics better than the community does, not build impenetrable Frankenbooks that just don’t work, on the web or anywhere else.

Frankenbooks must die! CREDIT: House of Frankenstein publicity photo 1382-54, 1944

Genuine topic collections and genuine books both have important and indispensable roles to play in the information universe. Frankenbooks do not. They are a monstrous hybrid that bring only misery and ruin. Grab your torch and your pitchfork and call out the neighbors. Frankenbooks must die.