Topic size: Finding the narrative minim

The first question we need to address in seeking a theory of topic-based information design is the perennial “how big is a topic”. Whether we are talking about the reusable blocks that DITA calls topics, or about Every Page is Page One topics that are sized for a reader, the question of size is always the first one that people ask.

In the discussion of Keith Schengili-Roberts’ blog post, What Size Should a DITA Topic Be? (the discussion is on a closed LinkedIn community, DITA Metrics, not the blog itself), Katriel Reichman suggested “one idea, one topic”. Another approach that I have used in the past is to say that a topic supports one task. read more

We Must Develop Topic-Based Information Design

There is a lot of talk in tech comm today about topic-based writing, but very little about topic-based information design. This is a problem, because, in the age of the Web, and particularly of the mobile Web, topic-based information design is essential.

Topic-based writing is often perceived (and practiced) as nothing more than writing in small, potentially reusable, chunks. As such, it says nothing about what kind of information design those chunks will be assembled to create. Often, such topics are assembled to create books, or, sadly, the monstrosities I have dubbed Frankenbooks.  Seldom are they used to create something that a reader would encounter as a usable topic — that is, a sufficient treatment of a single subject of interest. read more

The Design Implications of Tool Choices

Every documentation tool has a built in information design bias. When you choose a tool, be it FrameMaker, DITA, AuthorIt, a WIKI, or SPFE, you are implicitly choosing an approach to information design. If you don’t understand and accept the design implications of your tool choice, as many people do not, you are setting yourself up for expense, frustration, and disappointment.

Too Big to Browse; Too Small to Search

Findability continues to be the bete noire of technical communication. This may be a parallax error, but it seems that findability is more of a problem in technical communication than in other fields. The reason, I suspect, is that many technical documentation suites are too big to browse but too small to search.

I have commented before on the somewhat counter-intuitive phenomenon that on the Web it is easier to find a needle in a haystack (The Best Place to Find a Needle is a Haystack). This may be counterintuitive, but it is easy enough to explain: search (if it is any more sophisticated than simple string matching) is essentially a statistical analysis function. A search engine works by discovering a statistical correlation between a search string and a set of resources in its index. read more

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

Cars, trains, and puzzles: three approaches to topics

Everyone is wild about topics, and rightly so. Topic-based writing offers many benefits for both readers and writers. But not all topics are created equal, and how you serve your readers, and how efficient you make your writers, can depend on which approach to topic-based writing you choose.  We can usefully distinguish three basic approaches, which I will call cars, trains, and puzzles.

Are We Causing Readers to Forget?


Copyright (c) 123RF Stock Photos

Could the way we organize content actually be causing readers to forget what they have read, or even why they were reading?

In a post on the Technical Communication Professionals Email List, Mike Tulloch provides a link to a study from Notre Dame that suggest that walking through doors causes people to forget things  ( The theory is, apparently, that passing through a doorway is a threshold event that triggers the mind to store away information, which then makes it harder to retrieve that information. Mike wonders if there may be similar threshold events in text: read more