Here's a question I've heard many times: How much domain knowledge do technical writers need?
When talking about domain knowledge, I'm referring to subject-matter expertise: a deep understanding of the product or field being documented.
So why do similarly phrased questions come up so often? I'd like to kick things off with a phrase I've heard from a QA engineer colleague once:
If the QA team doesn't know about a feature, it doesn't exist, and if the technical writer team doesn't know about it, users won't know it exists.
This really stuck with me, because it says a lot more than one would initially think. Let's unwrap this sentence a little:
If the QA team doesn't know about a feature, it doesn't exist: In practice, this means that if a feature isn't tested, validated, and exercised in realistic scenarios, it might as well not exist. From a user's perspective, a feature that breaks in unpredictable ways or behaves inconsistently is indistinguishable from one that was never implemented correctly in the first place.
If the technical writer team doesn't know about a feature, users won't know it exists: In other words, if a feature isn't documented, it's effectively invisible to users. Users interact with new functionality through documentation. When a feature doesn't have documentation, users can't form a mental model of it. They can't evaluate its usefulness or determine where to integrate it into their workflows.
As a result, undocumented (or poorly documented) features will inadvertently become underutilized and misused, leading to a point where the feature might as well not exist.
Domain knowledge
Before continuing further, we must further define what domain knowledge really refers to this context. Domain knowledge is a hard skill, just like those I outlined in How can someone become a technical writer? Unlike the skills mentioned there, domain knowledge is highly specific to a technical writer's current position.
Let's break domain knowledge down to avoid ambiguity:
- Conceptual knowledge means knowing what a feature does and why it exists.
- Operational knowledge is knowing how to use a feature and its common workflows.
- Implementation knowledge refers to understanding how a feature was built internally.
Reading these, you might immediately assume one can't effectively write about a feature without a proper understanding of at least the first two on this list. If that's the case, I'd say your assumption is correct.
But then the immediate follow-up question becomes: Do technical writers have to be experts in the technical field they are writing about? Do medical writers have to be trained medical professionals, or programmers who create software documentation?
It definitely helps, but it's not a requirement. The fact is that it's extremely difficult, and I'd say sometimes it can even become detrimental when writing to a beginner audience. Not only that, but we're talking about two separate skill sets. Acquiring the knowledge and experience to become a self-sufficient technical writer takes about 2–3 years, and the same could be said about any other similar field. The real issue manifests when one has to maintain both skill sets.
I spent a bit more than two years as a project manager, so I experienced this first hand. While working as manager, I didn't have much time to write documents. This resulted in my writing becoming "rusty" and in me getting blindsided by even simple mistakes. This became very apparent after I returned to writing and realized how much I had forgotten in two years. Anyone who has learned a foreign language can attest to the same. The minute you stop using a language, you'll start forgetting words, grammar, rarely used sentence structures, and more. While it's easier to re-learn things you've already learned, maintaining both skill sets simultaneously is usually impossible. Impossible perhaps is a strong word, so to reiterate, let's frame it instead as impossible while staying efficient. There's a reason why people in the modern world specialize in a single field.
Filling in the gaps
If we accept the fact that it's impossible to know as much as the SMEs about how a feature or product was created, we have to account for the fact that technical writers must still have some level of domain knowledge. So how do you fill in the gaps?
The answer is simple: by asking questions and reading documentation (meeting notes, tickets, pull requests). I already explained both of these in Writing your first document, so I wouldn't want to reiterate much. I would instead like to focus on how you can remain efficient in this manner.
You have to learn to ask the right questions. Asking, "So how does the feature work?" is vague and would require the SMEs to repeat lots of information already available. Instead, read everything available first. Try to understand what the feature is used for and how users would interact with it. Look at user feedback from the past or, if possible, test it yourself. Afterward, your questions will become more focused on problem areas. You'll then be able to ask more focused questions: "I noticed that our users struggle to understand what to do after receiving this specific error. I've found one explanation in this document, but it focuses on a best-case scenario. What happens if the user has a setup that differs from this? What’s the best way to resolve it?" These questions clearly outline a specific problem, share what you already know, and pinpoint the requirement to solve the problem.
Inadvertently, you'll gain domain knowledge just by reading and testing features yourself. Not only that, but you'll gain a specific set of knowledge available only to technical writers: user interaction with documentation. That's what you must learn to leverage. That's what truly sets you apart from SMEs. This could be, for example, focusing on how new users navigate the documentation. Is there an engagement drop on a specific page? Why could that be? Could it be that the documentation is lacking some sort of mental connection, such as one page not leading to another in a logical fashion? Or perhaps a crucial step is missing for users to understand how a specific feature fits into their workflows?
Overall, your job should focus on two things:
- The ability to measure user understanding, which could come from feedback or analytics.
- The ability to fill in the gaps in both your domain knowledge and to use that knowledge to aid user understanding.
Domain knowledge and documentation quality
Domain knowledge has a clear impact on documentation quality. If the person writing the document doesn't understand how the feature should aid users, then the document's quality will most likely suffer.
This doesn't mean you must understand everything. As I explained above, that would be impossible. It simply means you have to understand enough. You only have to know what the feature does and how users will interact with it.
A technical writer's job is instead to understand where users are struggling. You can be all high and mighty and say, "Well, it's clearly documented on this page; the users should look for it a bit harder." But if you look at the analytics and see that one piece of information is receiving, say, 10,000 views in a hypothetical scenario and a connected important section only receives 6,000 views, that should ring some alarm bells. The fix could be as simple as repeating some important information or adding a big, colorful note showing that this is important.
On the other hand, you must know when not to introduce noise into the documentation for a loud minority. If, in this same hypothetical scenario, you see that there are 10,000 views on a page and 9,980 on the connected section, but you are still receiving negative feedback from three people, your job then becomes to analyze the situation, explain your stance, and disregard the feedback.
Overall, I'd say it's important to acquire some level of domain knowledge, but it's also important to know when it's more efficient to ask for help. If you must spend 10 hours testing something when the same could be achieved by asking a question, you are wasting time. Time that could be spent on things that are your job to know, like how users are interacting with the documentation.