Narrative and Fact in Tech Comm

Based on the responses to my post Topic Size: Finding The Narrative Minim, I think I need to say a little more about what I see as the role of narrative in technical communications.

To set the stage with broad brush strokes: The purpose of technical communication is to enable action. Technical communication gives a person the information they need to act confidently and with success. Just how much information each person needs in order to act depends on how what they lack. Some need a word; some need volumes. read more

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

Wide World of Tech Comm

The discussion around Larry Kunz recent blog post The Salt of the Earth raises some interesting questions about the part that those of us who call ourselves “Technical Writers” (or some cognate thereof) can and should play in the wider world of technical communication.

In the comments, Larry says:

As technical communicators, we need to ask ourselves whether we’re content with a narrow role — merely producing end-user instructions — or whether we ought to become contributors, and even leaders, in the work of producing documentation in the broader sense. 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

Everything Else is not a Concept

In any system that attempts to classify the whole of something, there is usually a category that essentially constitutes “everything else”. In the terrible troika of task, concept, and reference, that role belongs to “concept”.  In Tom Johnson’s shapes of help graphic, which have quoted before, and repeat here, task has the shape of a procedure, reference the shape of a table, and concept the shape of plain text.

Tom Johnson's "Shapes of Help" graphic.

Tom Johnson’s “Shapes of Help” graphic.

Concept, then, stands for the plain, the generic, the featureless and structure-less. read more

The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference

Tom Johnson’s blog post Unconscious Meaning Suggested from the Structure and Shape of Help, includes a graphic showing three shapes of content:

Tom Johnson's "Shapes of Help" graphic. Tom Johnson’s “Shapes of Help” graphic.

These three shapes are meant to represent the DITA topic triad of concept, task, and reference. I didn’t get it. As I said in a comment on Tom’s blog, I was trying to match the shapes to something more specific. It was odd that I didn’t recognize them as concept, task, and reference, I said, because I have be “battling the tyranny of the terrible troika” for the last few years. Tom asked what I meant by “the tyranny of the terrible troika”; this is my answer. read more

On Being Misconstrued

If you write, you will sometimes be misconstrued. If you read, you will sometimes misconstrue what you read. These things are part of the human condition.

If you speak, you will often be misconstrued, and if you listen you will often misconstrue. These things are even more certain. But the beauty of conversation is that you can rapidly realize the you have misconstrued or been misconstrued and correct or seek correction until you and your interlocutor arrive at a common understanding.

It is not that simple when you write. I was misconstrued recently, by Joe Pairman, in an article in the CIDM e-newsletter. Based on his reading of several post in this blog and other writings, Joe accused me of misunderstanding minimalism in three ways. (The substance of what he has to say is worth reading, despite it being inspired by a misconstruction of my opinions.) read more