Once I was interviewed for a well-known tech company, and the interviewer asked me about a superpower I would like to have as a Technical Writer. I didn’t expect such a question, but my immediate answer, dictated presumably by my subconscious mind, was an ability to ask the right questions at the right time.
After releasing this thought, I started paying more attention to the correlation between how I ask questions and what answers I get. In this article, I want to share some lessons I learned which helped me to enhance the quality of communication with developers and, consequently, the quality of documentation.
Preparing questions in advance
The very first step in all instructions on creating a technical article is to investigate the subject you are going to write about. It is an extremely important stage since the outcome of this preliminary research is going to determine how the writing itself will follow.
While the instructions emphasize the impact of the investigation step on documentation, they do not always say what this outcome should look like.
For me, the best result of research that a Technical Writer can get is an excessive list of questions that they will direct to SMEs (Subject Matter Experts) when setting up the first meeting on the subject.
When you have this list of questions prepared in advance:
- SMEs have time to think through answers and clarify tricky points they may be not sure about;
- you have a clear plan for the meeting and won’t get lost in the flow of new information;
- you can widen the circle of SMEs who should be involved in the process at the early stages of working on documentation.
Formulating questions in a form of practical scenarios
Examples are always a good idea, even when it comes to asking questions.
If, during the investigation stage, you stumble upon a controversial statement, do not state your question like “What does it mean?”. You may get an even more controversial answer. Instead, try to design a possible scenario illustrating your understanding of the statement, and pose questions like “Am I right saying that if X, then Y? Or is it rather if X, then Z?”
If a scenario is difficult to process in words, try to illustrate it with infographics outlining those points you are hesitating about.
The more scenarios you offer to the SME — the faster you will receive an unambiguous answer. And, as a bonus, you will also have a ready-to-use example for the documentation 😉
Thinking through all potential options
Practical scenarios in questions are useful, but sometimes it’s not about designing a scenario, but rather thinking about all possible scenarios in advance.
Assume we have a microservice to document, and its logic depends on 2 configuration parameters — Parameter A & Parameter B. From the code, we figure out that each of them can take 2 values. Here, the point is that the microservice behaves differently depending on the combination of these parameters’ values. So, we have to designate all possible combinations to make the question on the service’s business logic the most comprehensive:
It’s a simple case when there are only 2 possible values for just 2 parameters. You may have to document a very complex software piece where there are dozens of parameters with dozens of possible values for each. Here, I would suggest finding out what are the most commonly used combinations at first and then elaborating on each of them.
Asking even the most stupid or evident questions
We are afraid to ask questions that can signal our incompetence. And while it is a challenging psychological barrier, Technical Writers must overcome it.
When a baby starts learning about the world, they ask tons of questions, and nobody considers them stupid or evident. Obviously, the baby doesn’t have enough context and experience to answer the questions by themselves. So is the situation with Technical Writers — they are children who constantly learn something new.
Asking “stupid” questions may actually serve you well:
- you will cut off wrong assumptions about the subject right at the beginning
And those wrong assumptions won’t beget irrelevant questions in the future. - they may lead to more clever questions
An SME may give you a completely new perspective on a subject that you didn’t even consider before, and you can elaborate on this perspective right away.
Questions are a great tool for communication, properly stated questions at the right time are a priceless tool for effective technical communication. And yes, you will spend significant time and effort to prepare them, but you will certainly save up more working on the documentation later.
