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.

Findability vs. Searchability

I argued in Too Big to Browse; Too Small to Search, that search works best when it has a large amount of content to work with. But it occurs to me that there is a really important caveat to be made, which I can best express as the difference between findability and searchability.

The distinction I want to make is not clear in the common usage of the words “find” and “search”. They are often used as synonyms, particularly in computer interfaces. But I think there is nevertheless a significant difference in the connotations, which points to a significant distinction we should pay attention to when we think about the findability of our content. read more

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

Characteristics of EPPO Topics: Stay on One Level

One of the less obvious but more important characteristics of an Every Page is Page One topic is that it stays on one level. As with the other characteristics I have discussed in this series, being standalone, having a specific limited purpose, and establishing its context, staying on one level is not an ideal, but a common feature of millions of page-one topics on the web. What makes this characteristic worth pointing out is that it is something a topic does not share with books.

Approximation, Correction, and Tech Comm

Charge of the Light Brigade

Charge of the Light Brigade

At the Battle of Balaclava, an order reached a brigade of light cavalry to take the Russian guns. The general who sent the order was referring to a small artillery position that had been abandoned. But the commander of the light brigade could not see those guns. He could only see the main Russian battery at the end of the valley. He charged, and the light brigade was cut to pieces. The Charge of the Light Brigade can tell us something pretty interesting about the development of technical communication today. read more

Topics and the Big Picture

Writers often express the concern that topic-based writing cannot handle the big picture. Topics, they complain, don’t provide a way to tie everything together. Thus users get lost in a sea of topics, can’t understand the system as a whole, and can’t figure out where to start.

If you formed your topic set by slicing up a book, then the above is probably an accurate picture of the result. Scattered fragments of a book generally don’t do as good a job as the intact book. No wonder that so many writers, having split their books into topics,  hurry so quickly to stitch their topics back together into books, leaving themselves, in terms of information delivery, right back where they started from. 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

The Reader is the Enemy

Noz Urbina asks, Is Communication Mired in the Past? Well, yes, obviously. Most of the tech comms world is still making books in FrameMaker. But also no, because the problem is more profound than the words “mired in the past suggest”. People get mired in things through carelessness or misfortune. They want to get out, but they can’t. Technical communications isn’t mired in the past, it is entrenched there, gallantly, if with dwindling hope, guarding the battlements against the encroaching hoards of readers. read more