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.

Frankenstein and villagers

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.

, , , , , , , , , , , , ,

14 Responses to Frankenbooks Must Die: A Rant

  1. bg 2012/02/25 at 21:11 #

    Awesome entry. As someone who’s just moved Frankenbooks from an old Word-based system to a wiki, your article really rubbed it in that while the Wiki might make things better, it doesn’t necessarily do so. I really need to tune my own perception towards recognizing the wrong patterns and improving them as far as I can.

    • bg 2012/02/25 at 21:24 #

      On second thought, it’s not a Frankenbook because many of the contents are rather EPPO style, but it’s still not as good in that regard as it should be, as many older documents are long and complex and there’s too much redundancy. I’m writing online help for a decade, which has a strong EPPO factor, but I still never have thought about this in that much detail and regarding all the consequences. Thanks for making me think.

      • Mark Baker 2012/03/01 at 11:46 #

        Thanks for the comment. It has certainly been my experience that migrating content from book style to topic style is very difficult. Writing EPPO topics from scratch is not difficult. As I have argued in several posts (starting with http://everypageispageone.com/2011/08/09/every-page-is-page-one-topics-are-everywhere/) EPPO is actually a pretty natural style, which many people do well without thinking about it in any formal terms.

        But book style is so very different (and so very much harder to do well) that converting existing books to EPPO topics is very challenging. Actually, I think this is one of the main factors that has led to the rise of Frakenbooks: people needing to migrate and needing a way to get their existing content into its new form, essentially demanded a way to do Frankenbooks so they could get their conversions done within a product cycle.

        The other factor driving Frankenbooks is the desire to do reuse, which in itself has nothing to do with a switch to EPPO topics. One could get a substantial cost savings, especially for content that is translated, by moving to fragment-based writing of books. But this often leads to the books becoming Frankenbooks.

        The tragedy is that many of the people who have made the switch are now writing Frankenbooks from scratch.

  2. Michael 2012/02/27 at 13:50 #

    GREAT post, and thanks for including usability. My way of thinking about this has evolved so much that I think of my output as a “consumable” – who will consume topics/content and how easy is it to find and digest? Thinking this way is critical for Knowledge/Information management.

    • Mark Baker 2012/03/01 at 11:54 #

      Hi Michael,

      I agree. Users generally consume technical content as a snack, not a meal. There are time when we all appreciate fine dining, but when we are in a hurry, all the paraphernalia and time consumption that goes with the fine dining experience is simply exasperating. EPPO topics are snack-size tech comm. Frankenbooks are a dog’s breakfast.

  3. Mysti Berry 2012/02/28 at 10:11 #

    Regarding Sarah’s remarks–it depends on the wiki! The enterprise version of Google Sites lacks the admin features necessary to allow the change, navigation, or search required of genuine topic-based writing, leading the non-writers (and writers in many cases!) to create hopelessly long topics, or leave topics in an impossible-to-search-or-navigate state.

    Regarding the rest of your post, is there an example of a doc portal that does search and navigation well? I see portals where things have been dumped and left to search, but the containers are still books, making search difficult. Would love to see your examples of an info architecture done right for tech doc.

    • Mark Baker 2012/03/01 at 12:14 #

      Hi Mysti,

      Actually, I would argue that wikis are always about topic-based writing — they certainly are not about book-based writing. They generally don’t support component-based or fragment-based writing, though I believe some do have transclusion mechanisms. But transclusion alone is not much use without structure and content management, which wikis generally lack.

      To say that wikis are about topics, however, is not to say that they are about *good* topics. For one thing, they are about unstructured topics, so there is not much discipline applied (though I understand that some have template features that could help, at least). The other factor is that the community refactoring of content that was at the heart of the original wiki philosophy is seldom encouraged or practiced today (outside of Wikipedia). Pages in corporate or docs wikis today are generally owned, either tacitly or through enforced permissions. Thus bad pages stay bad pages.

      Like you, I can’t think of too many examples of doc portals that do search and navigation well. Then again, I seldom use the search facilities of individual help systems since I discovered that searching Google worked better (http://everypageispageone.com/2011/10/12/the-best-place-to-find-a-needle-is-a-haystack/).

      Most doc portals, in my experience, tend to be populated either with a dump of books, or with some kind of Frankenbook creation. Like you, I would love to know about ones that really work. The biggest impediments to effective navigation of tech comm on the web, in my view, are the lack of EPPO topics and the lack of linking. EPPO topics give search something worth finding (as opposed to dumping you into the middle of something unnavigable). Linking lets you move around in the content once you have found it. The Web is not a world of hierarchies, but of searches and links. (See: http://everypageispageone.com/2012/01/12/websites-are-upside-down/).

  4. Daniel Loftus 2012/02/28 at 15:28 #

    Several tools are available to migrate wiki content to alternate formats (http://www.mediawiki.org/wiki/Alternative_parsers). Mylyn Wiki Text is a tool that can migrate wiki content to a bookmap with multiple topics.

    I can see how adding keywords and reltables might be an area where a technical writer could add value during conversion from wiki content to DITA, although even this functionality could be defined by any writer (professional or in the community of writers) and these meta-tasks could be built into future versions of a wiki WYSIWYG.

    I can see what you are saying about the difference between writing the topic as a method and style of information design and writing the topic as a compositional mechanism. I think a writer could provide the most value if a DTD or tool could somehow automate or enforce the writing of a topic as a style of information design. In the context of wiki information development, it would be the absence of compliance with this style which could be the point at which a writer could provide the most value by injecting themselves into the information development process.

    • Mark Baker 2012/03/01 at 12:44 #

      Hi Daniel. Thanks for the comment.

      A DTD or schema can do a great deal to enforce topic-based writing as an information-design (Every Page is Page One) approach. DITA DTDs are not designed to do this, because they are based on the information mapping paradigm, but you certainly can write DTDs/Schemas that do this. The SPFE architecture is designed to enable this (see http://SPFE.info).

      I have written before about how you can do structured writing and crowd-sourcing together: http://everypageispageone.com/2011/11/20/do-structured-writing-and-crowd-sourcing-mix/.

Trackbacks/Pingbacks

  1. The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference | Every Page is Page One - 2012/07/30

    […] There is, of course, nothing preventing DITA users from having or developing a sound theory about how the pieces should go back together. The problem is not that DITA does not provide one. The problem is that writers often do not see that they need one. They believe, or act as if they believed, that the devolution into concept, task, and reference is a complete information design. The result, generally, is Frankenbooks. […]

  2. Misconceptions about Topic-Based Authoring | I'd Rather Be Writing - 2012/08/10

    […] Frankenbooks Must Die: A Rant […]

  3. The Paradox of Tech Comm | TechWhirl - 2012/09/25

    […] is a great XML editor supported by a fantastic company that is a joy to deal with. Its docs are Frakenbooks. ANT is a great (if sometimes eccentric) tool for creating build scripts. Its docs are abysmal. […]

  4. What Does “Every Page Is Page One” and “Include It All, Filter It Afterward” Mean? | I'd Rather Be Writing - 2012/12/08

    […] page they were supposed to. But since I don’t follow this practice (what Mark calls “Frankenbooks“), I can’t analyze the […]

  5. What Does “Every Page Is Page One” and “Include It All, Filter It Afterward” Mean? » eHow TO... - 2013/01/03

    […] page they were supposed to. But since I don’t follow this practice (what Mark calls “Frankenbooks“), I can’t analyze the […]