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. read more

Characteristics of EPPO topics : standalone

Last month I wrote that Every Page is Page One Topics are Everywhere, and I listed the principle characteristics of such topic as I see them. I said I would write in more depth about each of these characteristics. This is the first of those posts, on the standalone property of EPPO topics.

The word standalone is open to many interpretations. I have written before on what standalone means from the point of view of an authoring system and made a distinction between a chunk of content being able to exist alone (inside a CMS, for instance) and it being able to function alone for the reader. Here I want to look at what it means for a topic to function alone. read more

Topics are About User Assistance

Many discussions of the advantages or disadvantages of topic-based documentation seem to neglect the different view of the user that is inherent in the move from the traditional textbook style manual to standalone topics. Topics are not simply a new mechanism for composing and constructing documents, nor are they simply about enabling reuse, or about adapting to the web, thought the capabilities that the web offers are tremendously important to the real change that is going on.

What topics are really about is a new model of how users use documentation. Specifically, it is a move away from the educational model of documentation in which the manual was conceived of as a textbook, to a user assistance model in which the documentation is conceived of a an immediate aid to a user in the middle of a task. read more

What is a topic? What does standalone mean?

Everyone agrees that we should be writing in topics. (Okay, not everyone, probably, but everyone who is likely to read this blog.) Everyone agrees we should write in topics. But no one agrees on what a topic is.

Actually, that’s not entirely true. When asked to describe what a topic is, almost everyone in the business will come up with the same essential adjective: standalone. Everyone agree that a topic is a standalone piece of content. Unfortunately, no one agrees on what “standalone” means. read more