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.