Domain Knowledge: The Soul of Technical Writing
- Ravi Dhumane
Imagine you are documenting a data analytics software that takes discrete observations as inputs and transforms the dumb data into figures that tell a story. Assume this to be a slice of some retail data over a period. The information you get is how your customers are spending their money: on grocery and essentials, on personal care and lifestyle products.
Your team has put the best imagination and hard work together for this offering. The team is excited to launch this product and eager to see how it sells in the market. The team has entrusted you with the responsibility to do the necessary documentation. They are hoping that your documentation will be as impressive as the software.
Being techies, the team does not know what it takes to deliver the best user assistance contents. If required, they are all prepared to provide the best support: creative art, visual aids. Everything.
Finally, everyone gets to see what is going to accompany as the documentation-something that will do all the talking before the actual application does.
What they see after a long wait is a dry account of what the software features do. Something like, “The segmentation module creates a segment of customers satisfying the given criteria.” This is followed by an equally dumb account of how to use the feature: “For Customer Category, select a customer category from the drop-down list.” To their utter displeasure, they discover that what is written as user assistance text is no different than what was written in the design specifications for the features.
A basic ingredient that is missed in all the heap of written work is called the domain knowledge. A technical writer with the appropriate domain knowledge selects and tunes a narrative with as much thoughtfulness as a tennis player chooses to play the winning strokes. A few questions then arise as to what domain knowledge is all about and where one gets to learn it.
Let us Understand Domain Knowledge
Domain knowledge is the deep understanding of why certain business practices exist and how they support business. It is also to develop an understanding about various roles and what responsibilities they fulfil.
Let us understand this concept in detail in the context of segmentation that I mentioned above. Segmentation is used in Inside Marketing where a target customer base is identified. Imagine you borrowed customer data from a leads-supplying agency. You want to figure out how many of these leads are people whose kids are ready to go to school. You can approach those parents with an innovative learning solution. Here, you have applied the segmentation technique! To create this segment, you have applied filters on the demographic information, for example, a person in the age group of 25-35 years, married, and with annual income between 5 and 10 lacs.
How to Develop Domain Knowledge
The techniques I recommend are useful for an initial period when you are conditioning yourself to learn about a business. With practice, you will understand new businesses just by carefully listening to the subject matter experts. Occasionally, you may use one of the techniques where the business has complex workflows and you would want to demonstrate your understanding through reverse KT.
Data Flow Diagrams
For our inside marketing example, here is how a simple data flow diagram looks like:
Business Process Modelling
This technique is useful for carefully learning complex business operations across multiple operations units. Here, each operation unit is represented by a swimlane. The functions are represented by the typical flowchart symbols. Take a look at the following diagram to see how the business process modelling helps to learn an end-to-end process from order capture to delivery in a retail application:
Conclusion
Use of domain knowledge brings superior quality to user assistance content. With an increasing number of users who use applications with least prior knowledge, telling what data to enter and how, is not important. Sometimes, a mere click of a checkbox opens up an entire different user experience and writing a compelling story for such features is what technical writers are expected to do.
About the Author
Ravindra Dhumane is a software professional-turned technical writer. Apart from technical writing, Ravi has handled Project Management, Customer Support, and Quality Management responsibilities. He likes writing and blogging and go on long drives and also cooking.
