Reading Ray’s post, also sparks this thought. It is a common and sometimes catastrophic error to confuse an analytic truth with a synthetic truth. That is, it is an error to confuse a truth about how to analyse something into its parts with a truth about how that thing should be organized and presented to users.
While most of tech comm has moved to digital media — either to the web or to the product media — tech comm information design practices have been far slower to change. A large part of the tech comm world is still writing and delivering books, even if they deliver them as PDF or burst them into hierarchically linked help topics. This is a carry over from the design constraints of the paper world, and we need to move away from it.
Two of the key factors determining publishing strategy are the size and the time-frame of the content. Content may be large or small, and it may be topical (of immediate short term interest) or durable (of long term interest). In the paper world, different publishing and binding models fit different quadrants:
One of the most neglected aspects of the discussion of topic-based writing is that of provenance.
Every technical document has provenance of some kind. It may be a highly structured and elaborate provenance, such as certification according to a standard performed by an outside agency, or it may be the implicit provenance of being published by a brand name company.
Because of the implied provenance (not to mention implied liability) that goes with the publication of content under their name, most companies have some more or less formal and rigorous process for proving documents before they are released. In technical communications, this usually take the form of review and/or sign-off on a document by engineering and product managements (and sometimes legal).
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.
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.
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.
Concept, then, stands for the plain, the generic, the featureless and structure-less.
Continuing my reconsideration of concept, task, and reference as cardinal topic types, this post is about reference. I planned to call it “A Reference is Not a Table”, as I promised in The Tyranny of the Terrible Troika, but thinking more about it I realized that the issue is really much broader than that. The real issue is that a reference is not a topic at all, it’s a database.
In The Tyranny of the Terrible Troika, I complained that the now almost universal trio of concept, task, and reference did not properly represent what topic-based writing and information typing are really about, and I promised to show why each one, as popularly practiced, fails as both a topic type and as an information type. I begin with this: a task is not a procedure.
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.
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.
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.