During a recent online conversation, someone requested for a list of questions I would typically ask to a subject matter expert (SME) to prepare technical documentation for a topic. Of course, the parameters may vary, but there is still a list of questions that apply across all sizes or complexities of projects. In this post, I share with you the list of questions that I shared with them:
- Is there any legacy documentation available for the product? If yes, what does it cover? How can I access it? How relevant do you think it is? What else do you need me to cover?
- Are the documentation standards product specific?
- What is the background of the readers? Do they possess any prior knowledge of the product?
These question help me understand how much a user understands about the product I am going to write for. I can use the answers to these questions to determine the level of granularity at which I will cover something in the documentation bouquet. For example, if the user is familiar with the product or the legacy documentation, I may skip to advance-level concepts and features.
- What problems are the users facing?
This question helps me with a sneak peek into the business implications of the features. This is always a good question to ask, because you are most likely to shift your focus from writing about how things work to how the users can use those things in order to do what they want to do.
- What issues or pain points does the product or service resolve?
- Is there anything that the product or service doesn’t do?
These are extremely important questions, because I can use the information to build a premise around the features. Based on the level of granularity of the information I intend to achieve, I can delve into a topic. The simple questions like “Why”, “How”, or “What” help me do that.
- What all channels or formats do you need the documentation delivered into? For example, do you need a CHM or Web Help or only PDF documents? Do you require release notes? Do you require a knowledge base?
I use these questions to make a note of issues that impact more than one document. For example, I cover a known issue in the release notes as well as in the knowledge base (with the workaround, if any). If possible, I create a list of related or linked screens and features. I use this list to graphically represent the information flow.
- Who is the point of contact (PoC) for the project?
- What is the project deadline?
I prefer to create a backward plan based on the project deadline. And, I break the plan into activities and tasks. Later, I group those tasks based on the information flow. Each group has a goal. And, as I continue to complete these groups of tasks, I continue to improve the quality and the quantity of the content. I try to finish the technical-documentation iteration cycles a week before the final release date. Also, I prefer to run technical-documentation sprints in parallel to the code or test sprints after the second internal release. That way I can make room for the last-minute changes, if any.
- What resources are currently available for testing the product?
- What is the provision for tracking bugs in the product? On what priority are the bugs addressed in the product?
These questions are important, because they help me reach to the root of the problems. Also, I encourage the SMEs to provide the access to the bug trackers to me. That’s where the histories of issues are stored. So, that’s a shortcut to the core issues (and their respective resolutions or workarounds).
- What are the provisions with respect to the availability of resources, such as virtual machines and test environments, if any?
- Are there any budget, resource, or team constraints?
- What are the provisions of the documentation member or team participating in the technical-design processes?
In terms of the user interface (UI), questions like these will help determine the quotient of information findability in the product. The poorer the quotient, the more the scope and need for technical documentation.
- Does the base product allow for any customizations? If yes, what are they? How does a customer enable those customizations?
This is important, because I cannot – should not – write for customization-enabled products. First, I need to configure the product to its default settings. If there are differences in the documented and the actual user interface, the users may feel frustrated.
- Does the technical documentation require translation and localization? If yes, what are the requirements? Is there any translator/translator tool available?
- If I am lucky enough, how long do I get to test and edit the documentation before I release it?
This was my list of questions. I’m sure you too have one of your own. Can you make my list better? Do you have any question different from mine?
The Wordsmith 