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

Are Docs a Responsibility or a Business Asset?

Do we write documentation to fulfill a responsibility, or to create a business asset? Are we striving to meet a set of requirements pronounced by either convention or regulation, or are we striving to increase corporate revenues and contribute to shareholder value?

The question is provoked by an interesting discussion with Jonatan Lundin in the comments on Tom Johnson’s post Using Tags to Increase Findability. (The discussion has virtually nothing to do with using tags to increase findability — sorry Tom!) Jonatan’s position (if I have understood him correctly) is that tasks can be divided into product-centric  and organization-centric, and that documentation should stick to covering product-centric tasks and not touch organization-centric tasks. My position is that the user’s task is to use the product’s features to meet the organization’s goals and that if we are going to produce task-oriented documentation, therefore, we cannot ignore the user’s business domain. read more

Want Respect? Get out of Publishing

I recently wrote the following in a comment on Tom Johnson’s blog post What Tools Do Technical Writers Use:

That writers are still expected to do their own publishing strikes me as one of the tragedies of the profession, and a major part of why tech pubs does not get the respect it thinks it deserves in organizations. It is a big part of the reason that so many people still dismiss what tech pubs does as “making it pretty”.

It was not the most deeply considered statement I have ever written, and when I read it over after having posted it, I rather wondered at the sentiment it expressed. Why exactly should engaging in publishing lose you respect? It’s not as if people universally lack respect for publishing. It’s not as if publishing is something akin to pyromania or politics, rightly despised by all. Yes, there is the “making it pretty” thing, but why exactly should the ability to make content pretty lose you respect? People are not generally opposed to pretty. They like pretty. They pay a lot of money for pretty. read more

Tech Comm’s Place in the Choir

All God’s creatures got a place in the choir
Some sing low and some sing higher
Bill Staines

Birds on a wire

A place in the choir

Traditionally, technical manuals have been written as if they were the only source of information on a product. Of course, the manual was never really the only source. There have always been neighbors, friends, colleagues, retailers, user’s groups, and professional associations to learn from as well.  But access to these other sources of information was not universal, and those groups themselves had to learn from somewhere — information had to propagate through the network before it became available to the ordinary user, and the propagation was usually quite slow. It was reasonable, therefore, for users to look on the documentation as their principle source of information, and it was reasonable and necessary for the documentation to be written as if it were the sole source of information on a product. Not any more. read more

Why documentation analytics may mislead

I was rereading some material in the long-running do-people-read-the-manual debate (such as Tom Johnson’s If No One Reads the Manual, That’s Okay), and it struck me that there is an assumption that people on both sides of this debate are making which deserves some scrutiny. We all assume that technical documentation operates at first hand. That is, we assume that when a user wants help, they get that help directly by reading the manual or the help system or by watching a video, etc. I don’t think that assumption is correct. In fact, I’m convinced that it is naively and dangerously wrong, and that measurements and decisions based on this assumptions may be fundamentally flawed and harmful to a company and its customers. read more