Is There a Reproducible Method for Explanation?

By | 2015/10/15

In a recent LinkedIn discussion on “Most important competencies for technical writers,” I commented that the most important skill for technical writers was explanation, and that the ability to write and the ability to explain are not the same thing, and that the ability to explain is significantly less common that the ability to write well enough.

This scarcity of natural ability to explain well, I argued, is why we need to pay attention to tools and structure, because we need to find ways to help people who do not have a natural gift for explanation to explain things at least reasonably well. Tacitly, this argument suggests that there is a reproducible method for explaining things.

But is there such a method? Much hinges on this question, up to and including the question of whether technical communication is a profession.

In response to my comment, Robert Lauriston appears to reject the idea:


Explaining things well is essential to the profession. Tools can’t help you much with that part of the job, any more than they can with learning the stuff you need to explain. Someone who’s not good at both those is an unprofessional poser.

What skill at tools can do is free up your time to focus on those core tasks.

Lauriston is not reacting to the question of whether there is a method to explanation, as I did not state it explicitly in my comment. (It only occurred to me to frame it that way as a result of reading his reply.) But, generally, if there is a method, there are tools for that method. Generally, tools are designed to implement methods. Tools and methods go together, in other words, so the statement that tools can’t help with part of a job seems to imply that there is no method for that part of the job.

As to whether technical writers who cannot explain are unprofessional posers, all I can say is that I have read a lot of technical communication that meets the usual criteria set down for tech comm — it is well written, at least in the sense that the sentences and paragraphs are well constructed — but fails to explain the subject well. (In Story, Robert McKee makes a similar distinction between the ability to write beautifully and the ability to tell a story.)

If the people who wrote those works are unprofessional posers, I don’t know where the gifted explainers are going to come from to fill their places. How many of your teachers can you say were gifted explainers? We are not the only profession with a shortage of people with this gift. Yet the work of teachers and technical writers must go on, with the best people we can find to fill the jobs.

Let’s take this further. If there is no method for explanation, that settles the long-standing argument about whether technical communication is a profession (in the sense that doctors are a profession, for instance). Professions have methods. Professionals know and study the methods of their profession because they are proven ways to achieve superior results in an activity. If people are certified in a profession, they are certified on their knowledge of its methods and their ability to follow them. Professionals have tools that help them implement professional methods and they are expected to know which tool to use for which purpose and how to use them correctly.

Explanation is the core product of technical communication. If there is no reproducible method for explaining, then there is no method for technical communication, and it cannot, therefore, be a profession.

In the same discussion, Niels Grundtvig Nielsen wrote:


Tools are more useful the less you have to think about them.

But if tools encapsulate the essential methods of a profession, then you do have to think about them, because you have to think about the methods that they encapsulate.

However, it is a widely held belief in tech comm that tools don’t matter (as evidence by the sentiments expressed by other contributors to the LinkedIn discussion). And perhaps this is not surprising, because the tools that most technical communicators use have nothing to do with explanation. They are publishing tools and content management tools that by and large make no attempt to shape explanations in any way.

And since neither publishing nor content management are central to technical writing (they are ancillary for many, and irrelevant for some), it is fair to say that when it comes to the essential competencies of tech writing, the tools really don’t matter.

But if this is true, then one of the following propositions must also be true:

  • Technical communication cannot be a profession because there is no reproducible method for its core activity: explanation.
  • Technical communication is not yet a profession because it has not yet developed and codified a reproducible method for its core activity: explanation.

If there were a reproducible method for explanation, there would be tools for implementing that method and, as professionals, we should be using them.

If you are an Information Mapping person you are probably anxious to interject at this point and say that Information Mapping is indeed a method for explanation and that it does indeed have tools. But while Information Mapping is certainly welcome because it does introduce the idea of reproducible methods into the profession, it isn’t really a method for explanation. It is a method for exposition. That is, it is a method for organizing information so that it is easier to find. That is useful, insofar as it works, but it is not the same thing as explanation.

Practitioners of Minimalism probably want to make a similar claim, but though I believe in minimalism (though not for everything) I don’t think it is a full method for explanation. Rather, it is a method for providing optimal assistance for self-directed learning. That is important too, but it is not explanation. Sometimes, indeed, it deliberately stops short of explanation in favor of allowing the reader to figure stuff out for themselves.

(It is arguable that minimalisms demonstrated advantages over comprehensive documentation are attributable to the failure of the comprehensive documentation in question to explain well. In other words: poor explanation < minimal explanation < good explanation. Then again, the paradox of sensemaking has to be taken seriously, even when good explanation is available. )

The seven principles of Every Page is Page One information design are also an attempt to define a method for explanation, but while I obviously think the principles are important, they do not constitute a full formal method for explanation.

The STC has developed a certification program for technical writers which it hopes will solidify the status of technical communication as a profession. But nothing I have seen in it or heard about it leads me to think it contains a reproducible method for explanation.

If we believe that a method for explanation is possible and worth pursuing (and that, if attained, it would make technical communication a profession), then I believe the path to it lies through structured writing. Methods and tools are tied together. You cannot develop a method without encapsulating your ideas in tools that allow you to implement and test your method to ensure its reproducibility. Structured writing provides the basis for developing such tools.

Unfortunately, most of the emphasis in structured writing today is in content management issues such as content reuse. Considerable codification of practice has occurred in this area, though it is far from defining clearly reproducible results on a consistent basis. But none of this work is focussed on developing methods for explanation.

What do you think? Is there a method for explanation that can be taught to people who are not natural explainers and can be encapsulated in tools? If so, what do we need to do to find and develop it? If not, how do we justify calling technical communication a profession?

Or do you think such a method has already been discovered. And if so, why has it not yet been encapsulated in tools, and why is it not in broad use in technical communication today?

By the way, I was recently given a copy of Lee Lefever’s book, The Art of Explanation. I haven’t had a chance to study it, so I can’t say if it contains the method I am looking for. I’ll review it here once I have had the chance to go through it thoroughly.

49 thoughts on “Is There a Reproducible Method for Explanation?

  1. Marcia Riefer Johnston

    I like this question. Explaining requires many skills and tools (illustration, metaphor, etc.), but the most important one seems unlikely to lend itself to a method. The most important is the ability to anticipate audience questions and address them in a way that will resonate with that audience (those audiences). So many variables and possibilities come into play that I can’t imagine what a repeatable method would look like.

    (I’m eager to hear what you discover in this new book.)

    1. Mark Baker Post author

      Thanks for the comment, Marcia.

      If the most important part of explanation is to anticipate audience questions, then someone has developed a method for that. Jonatan Lundin proposes SeSAM (Search Situation based Architecture and Methodology) as reproducible method for anticipating user questions. He and I have discussed it several times in this blog (and in his blog). I’m not fully convinced by SeSAM, but I applaud the effort to define method.

      As far as resonating with the audience, I believe that studying topic patterns can take us a long way toward consistently creating content that resonates with audiences.

  2. Steven Jong

    If there’s a definable form of communication called “explanation,” then yes, it’s a core competency of ours, and if we can’t reproduce it, we’re not doing the job.

    But to progress further in the discussion, you have define what “explanation” is. I accept that we need it, but just dismissing various methodologies as “not it” is rock fetching.

    The certification language is that “it” is part of the overall body of knowledge of the profession.

    Pending a definition, I suggest that the process of explanation is detailed in any number of works on technical communication. Two that are on my shelf as I type this is How to Write Usable User Documentation, by Edmond Weiss (old), and How to Develop Quality Technical Information, by IBM (new). I’d start with the latter.

    1. Mark Baker Post author

      Thanks for the comment, Steven.

      I’m not sure that we need a definition of explanation to move forward here. Do we doubt what it means? Do the methodologies I mentioned actually claim to be methodologies for explanation?

      There may indeed by an number of books that touch helpfully on explanation. But that does not mean that they provide a reproducible method. There are a large number of books on fiction writing, for instance, that contain a lot of useful advice and information, that highlight common techniques used in successful fiction. But none of these create a reproducible method for writing fiction that can be encapsulated in fiction writing tools or used as a basis for a Certified Professional Novelist designation that guarantees its possessor can produce consistent high quality fiction.

      And maybe it is not possible to produce such a thing for technical writing either. In which case, the people who say that tools don’t matter are right, and there is nothing central to technical communication to certify, and the best any certification program is going to be able to do is certify ancillary and non-essential skills.

      I’ve seen and done things in structured writing that lead me to believe that a method is possible, but there is much work to do, and unfortunately the people working in structured writing today are largely focused on content management rather than explanation.

        1. cud

          I’d say if you haven’t defined “explanation” then you don’t have much chance of measuring whether a text explains well. If you can’t measure that, then how can you decide whether a tool is appropriate? If you can’t explain explaining, how can you explain whether an explanation explains anything? 🙂

          1. Mark Baker Post author

            Hmm, I think perhaps you need to define “define” here. I would not accept the proposition that defining and explaining are the same thing. 🙂

        2. Mark Baker Post author

          Language consists of a set of words and phrases that evoke common experiences. Definitions don’t create language because all definitions are expressed in terms of language — the classic bootstrapping problem. The role of a definition is to clarify which story you are using a word or phrase to refer to in a particular context. Thier function is to remove a specific form of ambiguity in a specific situation.

          Now, if we have an ambiguity about what explanation means in this context, then we do need to deal with it. But I can’t propose a definition that would deal with such an ambiguity until I detect that such an ambiguity exists and understand the difference between what I mean by explanation and what my interlocutor means by explanation.

          Definitions, in other words, are local responses to local misunderstandings, and cannot be usually created until we know where the local misunderstanding lies. If we continue this discussion, we may get to the point where I feel the need to define explanation in context, but I’m not there yet.

          Of course, if you or someone else does feel there is an important misunderstanding here, you should quite properly advance a definition yourself.

          1. cud

            So is specifying a tool a form of story? Because when you’re making a tool the definition is very important. You really can’t make a tool without it. So if you want a tool for explanations, you have to define what you mean. Otherwise I can’t develop squat.

          2. Mark Baker Post author

            If you are developing a tool to implement or support a method, then you need to define the method. You don’t have to define the object that the method creates except to resolve ambiguity between the people involved in the project. You can write a recipe for an omelet without defining the word omelet.

            If I see evidence that we disagree about what explanation means, I will attempt to provide a definition that addresses that specific disagreement. But you can’t define something in abstract without reference to a specific misunderstanding (other than the quote the dictionary).

          3. cud

            We just have to disagree on this I guess. I say you can’t possibly write a recipe for an omlette without knowing that it’s beaten eggs cooked in a pan in a certain way. The “knowing” in this context comes from the definition. It’s about specifying what the word signifies. In this case, a certain configuration of eggs, lubricant (usually butter), heat, and other optional ingredients. If you want to make an omelette “tool” (a special pan, for example) you can’t design it without knowing what an omelette is. Otherwise, how do you evaluate the design?

            I think you would get into trouble if you stepped into a design meeting and said it’s unimportant to define the final objective your tool is meant to produce or support. So we have to agree to disagree.

          4. Mark Baker Post author

            See, I knew that I was right to ask you to define “definition”! You are using definition as a synonym for knowledge. Definition, as I define it, is not knowing what something is. Definition is writing down what a word means to clear up a specific confusion. A definition is a literary composition. I can know what an omelet is without ever writing down a definition of an omelet, or reading one.

            I know what an omelet is because I have been served this dish many times and have been told each time that it is an omelet. I have tacitly grasped the parameters of omeletness from experience without ever writing down a definition of omelete.

            Now if someone were to ask me what the difference is between an omelet and a frittata, then I might need to define omelet, but certainly not to cook one or to write a recipe for one.

  3. Vinish Garg

    An interesting way to give the ‘due’ importance to tools that we often tend to disregard 🙂

    Even if we do not have a formal training in methods, we learn the art of explaining with experience, and from peers, readings, and community. Tools are facilitators that help us execute all this learning and our language skills. Btw, I recall one of your posts on tools at: /2013/07/29/why-is-writing-the-only-profession-untouched-by-its-tools/ and some great comments there.

    1. Mark Baker Post author

      Thanks for the comment, Vinish.

      Agreed, you do not need formal training in methods to do good work, in any field. Methods are simply the formalization of the best work that people do. Good work therefore comes before method. But methods are a way of enabling the most able people to do good work more consistently, and less able people to do better work than they could without the aid of methods.

      And yes, this post is very much a return to the themes of that post, with the addition of the focus on methods.

  4. David Worsick

    I feel that the difference between a help system that can be easily replaced by an overseas ESL workshop and one that has to be created by an experienced writer is the amount of explanation. Not about how to do a function, but when and what parameters to use for that function. It’s like learning to fight: being taught only how to punch, kick and block is like many of the minimalistic help I’ve encountered: not much help when I need it. You have to learn when and where to punch, kick and block, how to see an opening or a trap. In the minimalistic approach, you get beaten up a lot before you learn how. But if somebody explains how and when and when not, you might be able to defend yourself. I’m afraid that many help systems really don’t need much explanation. These are the jobs we’re losing to overseas. I also believe that many people really would like the explanations, but don’t realize they have to demand them from the companies. So, overseas it goes.
    I’m also both annoyed and amused that 15 years after I had an excessively long letter published in the STC about why certification wasn’t going to work (in 1998, from the Alberta chapter), the STC is still trying to develop it, and likely ignoring every issue I had brought up. Somebody else can try explaining things to them.

    1. Mark Baker Post author

      Thanks for the comment, David.

      I agree the what makes so many poor docs poor is the lack of any attempt to explain. You certainly do find it in offshored docs, but you find it in onshored docs as well. Far too many technical writers still understand their role simply as translating the SME into English. But if the SME can’t explain — and the SME is the one most likely to suffer from the curse of knowledge — then this process will not produce good explanations.

      And I sympathise with you entirely about the STC certification program. It seemed very much to put the cart before the horse — driven much more by the idea that a certification program would be a good thing than by any clear idea of what about the craft was objectively certifiable.

  5. Rick Lippincott

    I posted a much longer reply over on the LinkedIn forum, but I think the process of explanation can, in fact, be reproduced.

    The big part of the explanation that is often missing from documentation is the context. The classic tech writing drill is “How to make a peanut butter and jelly sandwich,” but no one seems to start by answering the question “Why am I smearing mashed peanuts and grapes onto slices of roasted wheat?” The answer is “To feed people.”

    Providing steps with no context is not an explanation. Providing a problem (“I’m hungry”) without a solution (“Make a sandwich”) is not an explanation.

    Providing an example of a problem and then documenting the steps to solve it puts the process into context, and that is an explanation.

    1. Mark Baker Post author

      Thanks for the comment Rick.

      I agree. I have written more than once to the effect that it is the job of the interface to explain the interface and the job of the documentation to build a bridge from the business problem to the tool. In other words, explain how the tools solves the business problem.

      But this leave open the question of whether there is a reproducible method for doing so.

  6. cud

    Take medical diagnostics for example. There are methods learned over the years, and many are codified. But at the bottom of it, a human still has to do it. Why? Because diagnosis is fundamentally an art… Backed by science, but an art just the same. Accepted methods do not ALWAYS apply, and human judgment is of primary importance.

    I’d view explanation in a similar way. Yes, you can give me tools to help, but I still need to use those tools — There is still an art to explaining. Situations always change, needs for and styles of explanation change. Media for explanations change (VR, anyone?). It takes an artist’s touch to respond to all the variables in a way that produces a clear and valuable explanation.

    Does that mean technical writing isn’t a profession? I don’t think so, any more than being a GP MD is not a profession. There is method at many levels of the “explanation” process — We could list a number of things today… These would be similar to the stuff you rejected, like minimalism or Information Mapping ™. They give rules, methods, and frameworks to accomplish different parts of “explanation”. But the final explanation is something a human has assembled for a human purpose. I think you would call that a story. It’s hard enough to define “story”, let alone establish a formal and all-encompassing method to product one of those things.

    1. Mark Baker Post author

      Thanks for the comment, cud.

      While I am still resisting the demand to provide a definition of explanation, it becomes plain that I need to define “method”.

      You are correct that while there are many diagnostic rules and tools, diagnosis still requires human skill. On the other hand, diagnostics without those rules and tools would be much less certain, regardless of the skill of the practitioner. This seems to me to frame what I mean by method.

      Method is not algorithm, in other words. An algorithm completely reduces a process to unambiguous rules which can be expressed by computer code. As long as the data is entered correctly, the result will be correct, regardless of the skill of the human being. There is not, to date, an algorithm for general communication or technical writing. (Narrative Science, through, claims to have algorithms for some forms of communication, such as sports stories and annual reports.)

      On the other hand, a method is more than principles. It provides more specific and direct guidance than principles. Methods can generally be expressed in or supported by tools. Methods help bring inferior practitioners up to a more professional level.

      I don’t reject minimalism and IM entirely. (I talk about both in the EPPO book.) But I pointed out that neither proposes itself as a method for explanation specifically. Also, while both have been around for a long time, neither shapes professional practice in tech comm the way diagnostic methods shape medicine.

  7. Lars

    In the end, this question comes down to: Is there a reproducible method for narration? Which leads to: Is there an algorithm for art? And my answer to that is: No, fortunately not.

    1. Mark Baker Post author

      Thanks for the comment, Lars

      But I disagree. There is a continuum here, with the phone book at one end and Moby Dick on the other.

      There is an algorithm for the phone book. There is neither an algorithm nor a method for Moby Dick.

      To plot your terms on this continuum:

      Tablular data —> Explanation —> Narration —> Art

      There certainly is not a method for art (though there are well define methods for depiction, for instance).

      There might be a method for narration. There is a better chance of there being a method for explanation — and more so for explanation of technical subjects perhaps, than say for politics or art.

      Secondly, and as outlined above, there is a difference between method and algorithm.

      1. Lars

        Sorry for mixing that up, I agree algorithms and methods are different, the alliteration was just too tempting. Also, you are right about technical communication being something else than Moby Dick (although tech writing sometimes may feel like being on a lonely hunt). But coming from liberal arts, I think that you are undererstimating the difference between what you call tabular data and explanation, and that you are overestimating the difference between explanation, narration, and art. I’d plot the terms on the continuum more like this: Tabular data —–> Explanation > Narration > Art. And because explanation is so much closer to narration and art:

        a) it is incredibly more difficult to find a reproducible method for explanation than for data description. Things like creativity, intuition, virtuosity, or cultural awareness come into play here. (Sorry, I’m not a native speaker, wish I could find better words.)

        b) tech comm does not require reproducible methods to be a profession. Neither does storytelling, and neither does artistry.

        So I have to revise my answer to your question: Yes, there could be a method, but finding it is probably very hard, and probably not necessary.

        1. Marcia Riefer Johnston

          Lars, Your answer strikes me as downright virtuosic. Your thoughts echo my own, and you’ve expressed them beautifully. I especially like your rendition of the continuum with the extended arrow. Your answer in itself exemplifies an explanation that would be difficult, indeed, to fit into a repeatable method of explaining (although if anyone can pin down such a method, it would be Mark).

          Mark, perhaps you will disagree and claim that Lars is not, in fact, explaining here, in which case we shall discover ourselves in need of a definition of “explanation” after all.

          1. Mark Baker Post author


            Given your association with the intelligent content folk, I find it a little surprising that you are coming down so strongly against method. It is hard to see how you can have intelligent content without method.

            I suppose you might argue that the intelligence in intelligent content had nothing to do with the content per se and is just about intelligent management of content. But even on that construction, dividing content into reusable chunks and assembling them into different documents seems necessarily to imply a reproducible method for constructing effective texts — texts which explain. So how can you do that if there is no method for explanation?

            Now, I am of the opinion (which I have not been shy about) that the current practice in this field does not constitute a good method for explanation. But surely it is an attempt at defining a method for explanation?

          2. Marcia Riefer Johnston


            It seems to me that intelligent content relies on structuring content components in context-specific ways based in an analysis of a certain organization’s certain content set. Whatever patterns emerge from that analysis reveal the opportunities for reuse, repeatability, consistent structure, automation—intelligent content—within that context.

            I read your discussion as a generic inquiry into explanation, which strikes me as a different thing altogether. If you can discover a method, more power to you. I’m following with interest.

          3. Mark Baker Post author


            I think it is pretty clear that any method for explanation is specific to explaining a particular subject to a particular audience. Thus a recipe is a is a method for explaining how to cook a dish to an experienced cook. An API reference is an explanation of how to use an API to an experienced programmer.

            This is similar in spirit to “structuring content components in context-specific ways based in an analysis of a certain organization’s certain content set.” The question is, is such an analysis done with the goal of improving explanation (as opposed, say, to the goal of maximizing reuse). In practice, it seems to me, that it is often not done with that goal in mind, and often does harm to good explanation.

            But is the specific methods are specific to subject/audience pairs, what I am looking for is perhaps not so much a generic method as a meta-method. In other words, is there a method for figuring out what the specific method for a particular subject/audience pairing should be.

            In no small part, such a metamethod has to address itself to the conquest of the curse of knowledge, which prevents people from discovering the best method for explaining a specific subject to a specific audience.

          4. Marcia Riefer Johnston

            “Metamethod” strikes me as a good word for what you’re talking about. Your question “Is there a method for figuring out what the specific method for a particular subject/audience pairing should be?” might well borrow from the teaching profession. It’s like asking “What method do teachers [in their role as explainers] use to help them pick from the many available tools to help their students arrive at aha moments in [subject a, subject b, etc.]?”

          5. Marcia Riefer Johnston

            If this interface allowed me to edit the note I just posted, I would change “tools” to “methods” in keeping with the way you’re using terms.

        2. Mark Baker Post author

          Well, if we want to examine where things stand on the continuum, we can begin by observing how many forms of explanation are actually quite tabular in design.

          My go-to examples here are recipes and API references. In each case, there are a number of fields, each of which has a well recognized format. There is discursive text in some of those fields, but its role in the overall construction of the explanation is well established.

          There is, in short, a method for writing a recipe or an API reference. There are also tools, such as Doxygen or JavaDoc, that help you implement the API reference writing method.

          Now there are certainly elements in those discursive passages that a more skilled writer might accomplish better than a less skilled writer, such as choosing a more apt metaphor for example, but a method does not have to govern every jot and tittle of the text to be useful and reproducible.

          When we say that there is no method for something, I don’t think that we mean that it is performed by some mystical force. I think we mean that it is something we learn by osmosis — something that comes from tacit knowledge that was acquired by experience rather than explicit learning or explicit formulations. Learning to catch a ball is an example of this kind of learning.

          There is method to these things, in the sense that they are products of brains. (I fully accept that The Messiah was inspired by the Holy Spirit, but I doubt that same can be said of the FrameMaker User’s Manual, for instance.) But there are certain methods that brains can perform that we cannot fully explicate and define. So the question is, is there a method for explanation that can be made explicit.

          I believe that there are two components of explanation:

          • What is said.
          • How it is said.

          Clearly the template of a recipe or an API reference entry tells you what needs to be said. To a certain extent, they also tell you how to say it. These things are codified into a method which many many people have successfully followed.

          On the other hand, no one has successfully codified a method for writing a literary classic like Moby Dick.

          So I would suggest that there is evidence that explanation, or at least the explanation of a certain broad class of subjects, is indeed nearer to tabular data than it is to art.

  8. Diego Schiavon

    Thank you for writing this, my Monday suddenly turned more meaningful.

    I was thinking something along the same lines during my commute a short while ago.

    I see discomfortingly little explanation in today’s documentation. Like a magical power lost in the mists of time and mechanical typewriters.

    I think approaches like minimalism, structured authoring, separation of content from presentation and controlled languages are trying to cut the clutter accumulated during the desktop-publishing binge, but what is left is
    disappointingly little: $5000 manuals no one wants to read instead of $50000 manuals no one wants to read. An improvement for sure, but still manuals no one wants to read.

    But I doubt explanation can be made into a reproducible method. Not any more than evaluating US teachers to death will make them better teachers.
    Or programming certifications make for better programmers. Or training certifications for better trainers. Or MOOCs for better students.

    Explanation is just as part of the paradox of sensemaking as everything else: the only people qualified to teach it are those who broke the paradox, and the only
    people qualified to learn it are those with an innate talent for it (or who took the time to break the paradox themselves, but that is not something you waste your time on if you have no talent for).

    That is, by the way, at least the literal meaning of “profession”: a mentor-pupil relationship between like-minded individuals with a special talent.
    Technical communication is a profession exactly because explanation cannot be taught to just anybody.

    I do not think a tool that encapsulates explanation can exist. We would end up with a more advanced equivalent of DITA’s Frankenbooks. Pointless exercises in misguidedness.

    My deep, deep thanks for your relation: poor explanation < minimal explanation < good explanation. My worldview has shattered and I am still trying to put the pieces together.

    I think the best a reproducible method can aim for is minimal explanation. Let us call it the 99%-transpiration threshold. Good explanation is the 1%-inspiration threshold, and that is not for everyone to achieve.

    1. Mark Baker Post author

      Thanks for the comment, Diego

      I think it is well established that methods have made programmers better and programs more reliable. Object oriented programming is a method, which a very comprehensive set of tools to help programmers implement it.

      Methods are not foolproof. They don’t guarantee that everyone trained in a method will perform exceptionally. In fact, I would venture to suggest that methods make good people better, and great people faster and more consistent, but that they don’t do much for weak people, if only because their weakness is that they don’t properly understand the method. Methods misunderstood and poorly applied can certainly lead to disaster. But we value them, nonetheless, for their capacity to make good people better and great people faster and more consistent — sometimes orders of magnitude better, faster, and more consistent.

      Certification, of course, is only going to be an indicator of future success if it accurately measures understanding of and ability to execute a method. Unfortunately, many certifications are not based on sufficiently defined methods or don’t do a good job of measuring a person’s ability to execute them.

      The claim that explanation is itself bound by the paradox of sensemaking is an interesting one. If we take the paradox of sensemaking to its ultimate conclusion, I suppose it would suggest that explanation is not possible at all, and that all we can do is encourage exploration.

      But while I accept that the reader will often turn to exploration, and will often benefit from it, I think it all comes down to stories. We learn by acquiring stories, and we can acquire them either by being told the story or by building our own stories based on experience. The question is, which is more efficient?

      Since stories are built on experiences, some base set of stories just has to come from experience. But many other stories can be learned by reference to stories we already know, and if we could not do this, we would not be able to learn much, and we would have a hard time advancing as a civilization. In fact, one could argue that the distinguishing feature of human beings is our ability to learn stories via language rather than experience.

      By itself, learning a story though experience is less efficient than learning it through language — it has more overhead. The problem is finding the right telling of the story we want to learn. Often it is hard to find the right telling, and often because we don’t know how to look for it.

      But this seems to leave room for the development of a method for constructing better stories and making them easier to find.

  9. Alex Knappe

    As a guy that is trying to fit stuff always into logic, it is pretty obvious to me, that good explanation is a matter of metrics in the relation between sender (tech writer) and receiver (audience).
    We are usually bound to one-way communications in our profession, due to a lack of timely feedback. Sometimes we do have asynchronous feedback available through wikis, CRM and other means. But this is minor.
    So, what a method needs first and foremost is metrics that can be applied without the need of direct feedback. These metrics already exist to some extent.
    The first subject we use our metrics on is the reader – our audience. We can classify him by several means like personas, sinus milieus and personal estimation.
    The data collected out of these methods delivers basic variables we apply to our content: depth of explanation, terminology used, etc.
    The second subject we are focussing our metrics on is the object we are going to explain. Do we have all the data about it? Are there interfaces to other world objects that need additional explanation? There are methods to gain these kinds of metrics as well: checklists, data sheets, visual and manual exploration, etc.
    The third subjects we can use metrics on are SMEs. Those guys give you the metadata about the object in concern. What’s the purpose of the object, how does it actually work and what are the main business problems it tries to solve. And also for these metrics there are well documented and acknowledged methods: interrog…err…interviews, question lists, demos, etc.
    All of these combined metrics build the foundation of our communication and it is also very possible to judge our work on them to some extent.
    Do we use the correct vocabulary for the identified audience, do we use explanation depth tailored to it, is all functionality explained, are purpose and main use cases explained?
    These are only simple questions for the sake of pointing in the direction of the method to use here. It ends up in a simple evaluation checklist, that in itself is able to produce metrics about how good a piece of information includes the necessary items.
    But those metrics are only good when they match metrics gained through the test against live subjects. There also methods to gain these metrics by using usability testing. These are also well documented and acknowledged.
    So in summary, it IS possible to measure the quality of explanations – it is just not being done on a daily basis. You may ask why not? The answer is: it’s not practicable – yet.
    We lack time and budget to create most of the metrics needed. Usability testing is being done for a few prestige projects. Judging the information needs to be done by human revision as we lack the automated tools for information analysis (initially I wanted to write text – but this doesn’t even get close to what is needed). We also would have to fit the information gathered into some kind of structured environment, which is nigh impossible (I’m already satisfied, when I can structure that in my head) due to time restrictions and the unorganized nature of raw information.

    To summarize my point: We have methods, metrics and the knowledge how to use all of it – but we do not have the tools, time or budget necessary to use them appropriately.
    So for the time being, we need to rely on our guts and talent to explain the subjects of interest. Some can do that easily, some don’t.

    1. Mark Baker Post author

      Thanks for the comment, Alex.

      I think you are absolutely right about metrics. The issue may not be whether it is possible to create a method for explanation, but whether it is possible to create a feedback loop to validate your method.

      This is important, because if a method cannot be validated, it might as well not be defined. If different writers propose different methods and we have no way to validate them, we have no way to refine the methods and agree on which are best.

      But I think the Web may give us a way out of this paradox. It is certainly very hard to validate the success of any one piece of content. But it is possible to validate patterns, even if we can’t validate the individual pieces of content that follow those patterns. And the web forms a marketplace in which successful patterns can evolve rapidly — something I have pointed out in the patterns of Wikipedia articles on different subject types.

      And if we can validate patterns, we can distil the characteristics that those patterns have in common. That is exactly what I did to come up with the seven principles of Every Page is Page One information design. And I think it may be possible to use the same approach to come up with a method for explanation.

      1. Alex Knappe

        Hi Mark,
        the problem with the web as a measurement instrument for metrics is, that the data points you can gather there are highly dependent on external variables. A method that seems to be valid for one thing (lets say a piece of expert software) can be completely wrong for another. This is not because the method is wrong, it is just wrong in combination with the external source (maybe some fundamentally different GUI).
        The thing with metrics is, that you can only get solid data points in a controlled environment such as a test lab.
        On top of this, there’s a lot about tech comm, that isn’t working on a large scale. Consumer products or widespread software have the best chances to gather solid metrics “in the wild”, but machinery or facilities lack the numbers and feedback channels to gather anything useful from a live environment.
        In my opinion profiling target audiences, gathering intel from CRM and technicians, observing the RMA and asking your wife/husband (no joke) turn in the best results.

        Apart from that, there are already tons of methods and models we are using in our daily work already. There’s no need of tracking down the “this works for everybody” explanation method, simply because there ain’t not “the one”. We can choose out of a myriad of methods, but if it works out (is falsified or not in the sense of a thesis) needs to be measured afterwards. To choose the right method for the right matter up front is, what experience tells us.
        One might say that this is unprofessional or unscientific, but that’s also true for the approaches engineers, architects or scientist take. See what has worked in the past and build upon it.

        1. Mark Baker Post author

          “The thing with metrics is, that you can only get solid data points in a controlled environment such as a test lab.”

          That is the traditional academic line, but it is not so. In fact, there are all sorts of data that can only be gathered in the field. The lean startup movement is particularly instructive in this area. The Web creates a near-perfect marketplace — that is, it generates information on customer preferences very quickly because it removes most artificial barriers to the sale and adoption of products. Thus the lean startup movement puts huge emphasis on getting a minimal viable product into the marketplace. It does not test products in the lab or in focus groups, but in the market.

          Also, we don’t need academic rigor in our data gathering. We are looking to improve, and the marketplace provides rigorous feedback that we can use to improve if we pay attention.

          “To choose the right method for the right matter up front is, what experience tells us.
          One might say that this is unprofessional or unscientific, but that’s also true for the approaches engineers, architects or scientist take. See what has worked in the past and build upon it.”

          Yes, method is not about being universal, but about fitting horses to courses. A method of explanation is a method of determining how best to explain a particular subject to a particular audience — which of a collection of techniques is useful in a particular case. But engineers, architects, and scientists have highly developed methods for fitting horses to course. Far far more than technical writers do. This is exactly what I am proposing: that we investigate how we can come up with a method for better fitting horses to courses.

          That an how we can better ensure that once the right method for a particular subject/audience pair is determined, it is actually followed.

  10. John Rosberg

    I am the only one that has thought of Robert Pirsig after reading the above conversation?

    Thanks for the food for thought, all.

  11. Diego Schiavon

    One of my personal idols is Niklaus Wirth, known among other things as the inventor of the Pascal programming language.

    He was a great scientist (still is, really, but I do not know well he has aged), well-versed in fields ranging from natural sciences and electronics to the humanities and pedagogy.

    He was also a great technical communicator: he wrote books about programming and edited other scientists’ papers (ever heard of “GOTO Statement Considered Harmful”, the seminal article by Dijkstra? Wirth edited it before submission, including the title).

    But I consider him mainly a great learner and a great teacher. He was the archetypical hero breaking the paradox of sensemaking, experimenting as a child with chemistry sets and rockets, and as an adult with compilers and FPGAs. Wirth was a tinkerer, and that was his way of learning about reality: try it out and see what happens (probably like in Pirsig’s book, mentioned by @John Rosberg).

    All his work can be seen as a teaching endeavour: Pascal was meant as a teaching tool, as were his other languages. He wanted learners to tinker with minimal guidance (see for example Program Development by Stepwise Refinement

    Like Mark wrote before:

    “If we take the paradox of sensemaking to its ultimate conclusion, I suppose it would suggest that explanation is not possible at all, and that all we can do is encourage exploration.”

    I am not ready to take the paradox to its ultimate conclusion – some explanation is necessary – but I believe that exploration is underrated. And I like to think that Wirth would agree with me.

    1. Mark Baker Post author

      I think that explanation is, in the end, a substitute for experience. We use it because experience itself is often difficult of dangerous or expensive or tedious to get. So we use explanation instead, to save time, to save money, or to stay safe.

      Explanation works by telling stories, which are virtual experiences. The effect of a story is to produce a vicarious experience without the difficulty and danger of the real experience. Vicarious experiences may not be perfect substitutes, but they expand our world and our capabilities.

      So experience is vital and you you can get it directly from exploration or vicariously from stories. The problem with the systematic documentation that John Carroll criticized is that it did not provide the experiences necessary for learning. Carroll focussed on changing that by encouraging more exploration, because he observed that people were exploring anyway, and suggested that docs that support that exploration would work better.

      Might people have explored less if the manuals has provided better stories? Maybe. He did not test for that. But what is clear is that for many products encouraging exploration is not an option because of the expense or danger involved. For really expensive machines, simulators provide an option.

      I think you are probably correct that exploration is underrated. And if so, the cause is the curse of knowledge. People in the know don’t appreciate the gulf that separates them from the inexperienced. But I would suggest that it is experience that is the core here. Exploration and stories are the two ways people can get the experience they need to learn. We should recognize that in many cases exploration is the only or best option. But we should also recognize that we could be much better at providing the right stories.

  12. Colin Keating

    The ability for a technical communicator to be able to explain is certainly critical. I suggest the ability to understand is equally critical an is essential before being able to explain. My experience with fellow technical writers and their effectiveness to explain has been their ability to understand what is being explained.

    1. Mark Baker Post author

      Thanks for the comment, Colin.

      Agreed. You can’t explain what you don’t understand. Though you can certainly understand something and still be unable to explain it.

      If there we could define a method for explanation, though, that could enable people who could not otherwise explain to craft a reasonable explanation.

      It is also worth noting that if we create a template for a effective explanation, then someone might be able to plug data into the that template and produce content that explained successfully to a specific audience without actually understanding the content themselves. But this will never be universal, and really an author doing this is not crafting the explanation, just posting data into an existing explanatory framework.

  13. John Garison

    Years ago when I was teaching technical writing, I came up with my own list of critical competencies for tech writers, complete with mnemonic: CIAO and R

    C = Conceptualize: successful writers are able to quickly form a mental picture of the problem, and from that, derive what are the most critical concepts and procedures that need to be explained.

    I = Investigation: successful writers avail themselves of whatever they can find to learn more about the task- specs, scenarios, blogs, proto-code, and people who understand the problem.

    A = Assimilation: successful writers can use the investigation to figuratively slap pieces of meat onto the skeleton of ideas that they initially conceptualized, and to change the skeleton as need to conform to what their investigation tells them. True assimilation results in an ability to understand what results when you change parameters.

    O = Organization: successful writers can figure out the best way to arrange the information they have learned so that it makes logical sense and builds in the reader’s mind an understanding that closely corresponds to the writer’s vision and knowledge. [IMHO, this is the most critical skill that the writer needs to have: the ability to determine the best way to organize and structure information so that the audience can absorb and use it.]

    R = Regurgitation: once a successful writer has done the first four steps, the writing down of it is pretty easy and happens quite naturally.

    So I guess my take on it is that Organization – the melding of structure and logical presentation of content – comes as close to a definition of “explaining” as I can get.

    My 2¢.

    1. Mark Baker Post author

      Thanks for the comment, John.

      This is helpful.

      ” [IMHO, this is the most critical skill that the writer needs to have: the ability to determine the best way to organize and structure information so that the audience can absorb and use it.]”

      I think that would work as a definition of explaining, for many purposes.

      So if we apply this definition to the question of whether there is a method for explanation, the question then becomes,

      • if there is a “best way” to do this for a given type of subject, does each individual writer have to reinvent or rediscover this “best way” each time they write about a subject of this type, or can we codify the best way for a given type of subject (as we have codified the best way to present a recipe or an API reference)?
      • and if we can so codify the best way to explain a given subject, can we define a method for discovering and codifying the best way of describing any subject?

      If we can, then we have a method for explaining.

      If we can’t, what are we claiming?

      • That each individual instance of a type of subject is so utterly unique that the best way to describe this instance is utterly unlike the best way to describe any other instance of the same type?
      • That the means by which we discover the best way to describe a type of subject is so complex and obscure, relies so much either on mystical insight or tacit knowledge that we cannot actually discover or describe how we do it?

      If we are talking about writing Moby Dick, I would accept these claims. Writing great literature does seem to depend either on tacit knowledge or divine inspiration, because we clearly can’t define a reliable method for reproducing it. But for writing a technical manual, I don’t think so.

  14. David Worsick

    Many people on this topic talk about telling stories and how there’s no method to do that. But there is a method to improve your story writing. Aside from my career as a technical writer, sliding toward retirement, I also am a would-be fiction writer (fantasy and science fiction: not yet published) who has taken a good number of courses. These courses are strongly based on feedback to what I’ve written and they do teach a heck of a lot. I definitely know how to write stories much better than I used to. However, there’s no set formulae: you can read how-to-write-fiction books for days and days and never, ever improve. It’s the feedback to what you’ve already done that matters.

    I do not see technical writing courses that can actually use the material you’ve written, compare it to the actual task, and tell you what you’ve done well, what you’ve missed and how someone else would do it. Admittedly, that would require a teacher that knows your field and your readers, but if you can find one, you could benefit greatly.

    However, we don’t seem to train technical writers the way we train martial artists; there’s no “sparring” to see what may need changing in your style. Instead, people talk about systematized methods that will ensure good instructions the way people used to talk about fighting patterns, forms and special techniques that you could learn without actually being in a fight. Since the latter never worked as well as actual sparring matches, the former won’t work without showing your real work and getting good feedback on it.

    Just an idea.

    1. Mark Baker Post author

      Yes, the comparison with story writing is interesting. What we can see in that field is that some forms of story are much more amenable to formula — that is, to method — than others. Harlequin romances are highly formalized. So is much of the stuff the Disney produces for kids TV. This is commercial fiction as it most formalized and measured, and both companies are really good at it.

      There is, of course, still an element of art in these works, and no everyone can write them just by following the formula. However, for those with the appropriate skills, following the formula makes them consistently more successful and more productive.

      In other words, we don’t need a method for explanation to make morons into tech writers; we need a method for explanation to make competent tech writers and other business professionals into better and more productive explainers.

      Martial arts is a good illustration of the same principle. Martial arts teaches patterns of attack and defence. Physical stamina, strength, courage, and imagination are all necessary to use those patterns in a fight, but someone who has learned the patterns will be able to defeat someone of much greater physical gifts.

      Methods improve and perfect the gifts you have. They don’t obviate those gifts; they amplify them.

    2. John Garison

      Enter your work in an STC competition and you will get feedback on exactly what you have written from competent (in my experience) evaluators.

      1. David Worsick

        That would be the equivalent of a “blue pencil” session: helpful but not as helpful as I was thinking of, which is more of a half-week-long “writer’s circle/Clarion course”. That’s more detailed and actually involves learning why you wrote in such a matter (e.g. for technical writers: why did you write about these functions in this way and not include these other functions).

        Just as a good writing course asks why you want to write the story you’ve written, and what your writing aims were, we would need a course to make you think of why you chose to document the steps and functions you chose in mind of the audience you would likely have. Maybe the STC now have something like that, but I quit the STC in the 90’s because I was disappointed in them and what they offered.

        The industry would need something like this particularly since the art of mentoring seems to have faded away.

  15. Diego Schiavon

    I have been thinking about the question of a method for explanation in the past days. I came up with a couple of thoughts:
    a) Isn’t a “reproducible method for explanation” precisely Carroll’s “Nurnberg’s Funnel”? A magical object that can teach anybody a complex skill, but which is impossible because people make meaning based on their own context and background?
    b) I remember taking a course in Agile methodology. The textbook was not a thorough description of Agile’s tools and concepts, but an Agile-inspired novel, or fairy-tale as the authors admitted. It told the story of a company that adopted Agile to avert disaster, and succeeded.
    I remember I thought it was pretty useful. Of course with numerous caveats:
    – The book did not explain technology, but human interactions, and that is the stuff of novels.
    – Agile has a fairly limited set of tools that can fit in a novel without overburdening the narration. I guess Prince2 lends itself less well to being fictionalized. Or an NFPA standard.

    Still, maybe the potential for narrative and storytelling for technical communication is underrated.

    c) Not entirely related possibly, but Italian high schools use the “Hegelian method” of explaining everything in terms of history. So students of the better Italian schools essentially learn history of literature, history of maths, history of arts, history of philosophy, history of programming etc.
    Ideas are presented as moving from embryonal stages onto their more complete stages.
    The approach is of course 200 years old by now, has very nasty associations to totalitarian ideas of all kinds and has been proved lacking hundreds of times and is desperately useless in practice-related subjects. Still, it is a structured method for explanation and can still prove its worth on occasions.

    1. Mark Baker Post author

      Thanks for the comment, Diego.

      That’s a really interesting question about Carroll’s Nurnberg Funnel. Carroll’s point was that “systematic” documentation did not work because people suffered from the paradox of sensemaking — they could not cross the gap between their current worldview and the world view of the documentation. But Carroll then proposed minimalism as a method for dealing with the paradox of sensemaking. Not for solving it, certainly. Carroll is clear that there is no solution. The reader has to work their way through the hard process of sensemaking. But minimalism is an attempt to provide a method for creating material that is the most help and the least hindrance to the reader on that journey. It is, therefore, a method for explanation.

      Unfortunately, minimalism has tended to get reduced to a system, with many people who practice it apparently unaware of the paradox of sensemaking. The result is that they often produce barebones procedures of the very kind Carroll found people could not follow.

      And perhaps the same applies to the Hegalian method as well. All learning is stories, and history provides the foundational stories of every discipline. But some stories have to be learned in the flesh, hands on. So if you treat the method as a system, you will probably not get good results.

      So perhaps we need to make a distinction between a system and a method, where a system is something that can be followed without thought or imagination, whereas a method requires thought and imagination, but disciplines them, leading to a more consistent result.

      Certainly such a distinction would apply to agile. Agile included many practices, but any agile coach will tell you that adopting agile practices without developing an agile culture will not work. Agile requires understanding, thought, and imagination, and provides a way of disciplining these things to produce superior and more consistent results.

      But it seems to me that we lose a great deal when we don’t pay sufficient attention to method. On the one hand, there is a desire to reduce method to system, since systems require less thought and imagination, both of which are tiring to practice and expensive to hire. On the other hand, there seems to be a desire to exercise thought and imagination entirely unhindered by any constraint. But this is monstrously inefficient. We need method to discipline, guide, and support thought and imagination.

      Yes, that is meta: method means applying thought and imagination to the processes of thought and imagination, and that is hard. But it is what makes a profession a profession and what makes professionals consistent and productive.


Leave a Reply