Writing Excellence Through Domain Awareness

A little while back, Tom Johnson posted an article entitled Seeing things from the perspective of a learner in which he says, “The balance between knowing and not knowing is the tension that undergirds the whole profession of technical writing.”.

I think that is absolutely correct. The point, after all, is to assist the reader on their journey from ignorance to knowledge. I say assist, because this is not a journey that can be accomplished simply be reading. The reader has work to do to integrate their knowledge. They need to get their hands dirty. But a sympathy with the troubles and perils of that path is at very least, highly useful to the writer.

This does not mean that ignorance is a virtue, as some writers suggest. You do not gain any sympathy with the troubles and perils of the path from ignorance to knowledge without actually learning, and once you have learned, you write from knowledge, not ignorance.

But if you are taking that journey, Tom suggests, you should stop and make notes along the way. Record your questions and your difficulties so that when you arrive at the state of knowledge you have preserved you memories of the road and can use them to inform the travel guides you write for the next traveller.

All this is important because of the curse of knowledge, the cognitive bias that makes you forget the perils of the journey once you reach your destination. As I have suggested in the past, the journey from ignorance to knowledge consists of learning stories, and the way language works is by encapsulating stories in a way that makes us forget that they are stories.  Notes from the road seem like an excellent way to inoculate ourselves against the curse of knowledge by reminding ourselves of the stories we had to learn and the price we paid to learn them.

Still, I am not entirely comfortable with the conclusion that Tom draws from this. Tom summarizes his argument with this diagram:


It is the part about the space between knowledge and ignorance being the place you write the best documentation that bothers me. It is certainly the best place to gather useful notes on the journey from ignorance to knowledge. But I am uncomfortable with the suggestion that it is better to write in a state of partial knowledge rather than full knowledge.

All the same, I recognize that in the state of full knowledge one is apt to suffer from the curse of knowledge. So mere knowledge is not the best place to write from either.

So where does the best technical writing come from. What state do we need to be in to produce the best possible technical communication?

I think we have to reach for a different state, one which I will call domain awareness. I’ll diagram it like this:


Mere knowledge of a subject does not constitute domain awareness. We may understand the subject matter of the domain, but we don’t have full recognition of its status as a domain. We don’t know what things belong to that domain and what do not. We do not know what stories are unique to that domain and which are not. We do not know how language invokes stories in that domain that are not invoked in other domains. We do not recognize which concepts, ideas, and principles belong uniquely to that domain.

It is like knowing the city you were born and brought up in but having no idea which things, customs, laws, and people are common to all cities and which are unique to your own. If someone from another city asks you what is cool or unique or interesting or important about your city, you don’t know how to answer them because you have no idea what makes your city different from theirs.

Domain awareness means not only knowing the subject matter of your domain well, but also understanding your domain as a domain and its place in the universe. It is only in a state of domain awareness that you act as a useful and reliable tour guide to your domain.

Domain awareness is the antidote to the curse of knowledge.

Domain awareness is the thing that sets the great explainers, teachers, and writers apart from the rest of us.

Notes from the road from ignorance to knowledge are of undoubted benefit in forming a domain awareness, though they are far from constituting the whole of it. Our particular journey is from our own ignorance, which may not be the same as another’s ignorance. And even if it is, we may take a different route from others. Domain awareness requires a more comprehensive view of what makes the domain distinct.

Domain awareness is by no means an easy state to achieve, and much documentation must necessarily be written by people who have not achieved it. But it we want to identify the space where the best documentation gets written, it is domain awareness.



, , , ,

4 Responses to Writing Excellence Through Domain Awareness

  1. John Crossland 2016/05/01 at 05:09 #

    This is bang on about domain expertise. I had this experience myself when I was tasked to write better documentation than the vendor supplied for a Mac utility that converted colour palettes for Windows. I didn’t have enough domain knowledge as a Graphic Designer with PhotoShop to do it at first, so I got involved in Localization production work to learn enough about their job to write instructions for new hires. Going gonzo worked. I did the same thing writing networking documentation by first taking Cisco training courses to gain a better insight into how network admins learnt and worked. But it is hard to do this. Few firms will give you the time and funding to not write or edit to prepare to write.

  2. craig wright 2016/05/05 at 07:21 #

    Hmm…you have interpreted Tom’s diagram differently to me, Mark. Interesting though.

    I took Tom’s diagram to mean:

    The writer doesn’t need to have all-encompassing knowledge about the product to create quality documentation. Having knowledge about the specific topic at the time of writing is all that is needed. So the grey area represents the product knowledge, not the knowledge of the topic being written about.

    But after reading your post, I can certainly see where you are coming from and understand how you read it differently.

    I like the concept of domain awareness. If knowledge is the information, then domain awareness is like all the inputs we need for empathy.

    Perhaps it works like this:

    General tech writers are more in tune with the domain awareness and need to learn the knowledge.
    Specialist tech writers and SMEs are more in tune with the knowledge and need to learn the domain awareness.
    The lucky few are in tune with both and can do both quickly and effectively.

    I think memory plays a part too. Where you fit in the spectrum depends on how much you remember. We only need to be an expert on a subject at the time of writing (thank God!).

    • Mark Baker 2016/05/05 at 07:45 #

      Thanks for the comment, Craig

      That is certainly a reasonable interpretation of Tom’s diagram as well. I think my response would be the same though. But I really like your phrasing of “general tech writers are more in tune with the domain awareness and need to learn the knowledge”. I think this may be the thing — the attitude — that sets the professional writer apart. They focus on the development of domain awareness because they recognize that it is central to great explanation.

      And as such, my diagram may be a little off, since it suggests that domain awareness proceeds from domain knowledge. But while it is certainly true that there can be no domain awareness without some domain knowledge, it seems it is possible to have a degree of domain awareness that is far greater than one’s level of actionable domain knowledge. One can be better qualified to write about a domain than one is to practice in it.

      But this suggests that developing domain awareness is actually something distinct from learning about the domain. It suggests that when someone like Tom or myself, who both write for software developers, sit down to learn a new system or language, we actually have different focus from a developer learning the same system, that we are focused on developing domain awareness as opposed to developing domain knowledge. It suggests that there are elements of domain knowledge that are far more necessary to domain awareness than others, that there may be large amounts of domain knowledge that are vital to domain performance but not domain awareness, and that a writer with domain awareness can effectively research and write about them without developing or retaining a working knowledge of them.

      This seems to me a much more satisfactory explanation of the role of the technical writer than any I have heard offered before.


  1. Eluding the curse of knowledge | Leading Technical Communication - 2016/07/11

    […] Mark Baker says that the antidote to the curse of knowledge is domain awareness: […]