Recently, I came across the article “Seeing things from the perspective of a learner” by Tom Johnson that responded to my frequent apprehensiveness that the produced documentation would not respond to the real needs of the users it is produced for.
Very often, we start writing the documentation being a “blank page”, completely unaware of the domain and the application. And that’s when we first start hesitating whether we would be able to grasp enough information needed to make the experience of the users with the application more pleasant. We dig the technical and the domain details very deep and stop realizing that we already know too much to write the documentation that the real-life users with the real-life problems need. We forget those first “silly” questions that we once had at the beginning, and everything seems so clear to us, that we start producing the documentation that is either too hard to understand or contains too much techy details and almost no information for beginners.
Are there any tips to avoid the “curse of knowledge”? In his article, Tom Johnson shares some great recommendations:
- Take advantage of your product ignorance.
- Capture all the questions that you have while making familiar with the product.
- Refine the “dumb questions” really carefully, as further they may come in handy when structuring the documentation.
It seems, this article caught not only my attention. In his blog, Mark Baker also discusses Toms’ article and an important idea he adds is that product ignorance does not equal domain ignorance. We need to be aware of the domain as much as we can since we write the documentation for the users who are experts in this domain.
Mark adds a couple of ideas to Tom’s article, and I cannot help but agree with them:
- Domain awareness should mean knowing the whole context – not just separate subject matters.
- Domain awareness may help us understand the typical users’ pains with our product.
- Domain awareness helps us write quality and understandable documentation that explains and teaches.
- Domain awareness is a long and hard path for a Technical Writer, but still a rewarding one.
With this being said, I would also add that analyzing the users you write for (their daily routine, tasks, and troubles) is also one of crucial things to produce effective documentation, which in no way can be omitted or left out.