Meticulous research is the hidden essence of all quality technical documentation.
Technical writers don’t just sit down and write. They spend hours and days gathering information, talking to experts, and verifying their sources before they feel confident enough to draft documentation for their end-users.
All of this work can get rather intense, which is why we’ve prepared a list of practical, actionable tips that will make your research efforts much more manageable and effective.
Read on and find out how to quickly and efficiently find and use the knowledge you need to write quality technical documentation.
Ask the Right Questions
The importance of beginning your research with the right set of questions cannot be understated. The right questions will inform your subsequent writing and keep you on topic, while the wrong questions will lead you down the wrong path and make your research chaotic and pointless.
This is something technical writing experts agree on. For example, Kesi Parker, a veteran of the industry, emphasizes the importance of formulating your questions well in research:
If you succeed in asking the right questions, you will be able to come up with a solid problem statement. Dip into your prior knowledge of the subject to do so. The right questions will be your guidance. Do not underestimate them.
The questions you need to ask are the ones that reflect the desired characteristics of your future document. Here are a couple of examples to get you inspired:
- Who will be reading my document? (Audience)
- What type of information is needed? (Document type)
- Where can I find the information I need? (Knowledge)
- How can I present this information for optimal user experience? (Formatting)
- What should be included in the final document? (Document resources)
By answering at least some of these questions, the methodology of your research will start to take shape, and you will begin to understand which steps to take to research your topic efficiently.
For example, if you’re researching connectivity issues with your product, the answers to these questions might lead you to the conclusion that you should write a troubleshooting guide (doc type) for IT administrators (audience).
These answers already point to the conclusion that you will need to focus on problems faced by users instead of, for example, user goals and that you’ll be providing highly technical information in the document.
This technical information could be obtained from the developers working on the product or the customer support team who has solved such problems in the past (knowledge).
Finally, by answering the last two questions, you might decide to ask for step-by-step instructions from the above-mentioned experts (formatting) and find or create screenshots and diagrams to go with your instructions (resources).
In this way, answering a simple set of questions has provided you with specific steps to find the information you’re looking for.
The research phase can now truly begin.
Identify Credible Sources
Before you dive deeper into your research, it’s important to identify which sources of information you can safely and confidently use in your research so as not to relay any inaccurate or outdated information to your end-users.
Your first and quite possibly the most credible source of information should be the product itself.
If you’re researching a certain feature in order to write a technical document about it, it only makes sense to explore that feature and see how it works for yourself.
For example, let’s say you’re documenting automation software, such as Zapier. Your first step might be to open the application and try out its features.
By gaining first-hand experience with the product, you’ll be able to write clear, accurate instructions for the product because you’ll be relying on your own knowledge.
Moving past the product, your next set of information sources are the company’s internal resources, which should be highly credible since they are so closely related to the product.
These resources can include subject matter experts (SMEs) that have developed the product or any existing internal documentation you can draw knowledge from.
The former will be discussed in a later section. As for the latter, these can be documents such as the comments and notes created by the development team or technical documentation created for a similar product.
These can be extremely useful for your research, but you’ll have to ascertain that they are accurate and up to date. A good way to do that is to ensure that you have the latest version of a document or to check if the document is marked as verified.
Some documentation software, Archbee included, has features that enable stakeholders in the project to mark a document verified and up to date, which makes it very unlikely that you’ll be using the wrong version.
The point of all of this is to ensure that you’re always working with information that’s as fresh and correct as possible, as this is the only way to ensure your documentation will be helpful to users.
In that regard, the people involved with the product, the information they’ve produced, as well as the product itself are your most credible sources of information.
Keep a Resource List
You may have deduced from our previous section that identifying credible sources might take some effort, especially if your company keeps meticulous records during product development.
There might be a lot to go through, so to save time and effort, it’s a good idea to build an archive of documents or a resource list so that you can always access quality information quickly and without rummaging through your company’s records.
For instance, let’s say your team is developing a new feature for your product and holding frequent meetings for it.
If you’re participating in those meetings, your notes could be an invaluable resource for your research process, so it’s a good idea to archive them carefully for later use.
If your team is holding virtual meetings on Microsoft Teams, you could even record them and build an archive of video recordings you can later access to find out crucial information about the product that will make its way into your documentation.
Similarly, if there are any online resources you frequently turn to when writing documentation, such as technical writing style guides, or code references, it’s a good practice to build a catalog of bookmarks so that you can access these materials whenever you need to.
Bookmarking tools such as Raindrop can help you with this.
Raindrop enables you to organize your bookmarks into collections and provides navigational help with tagging and highlighting features so you can find everything in a couple of clicks.
During the documentation process, you’ll need to frequently access a lot of different types of resources. To make your job easier, start compiling a resource list early on in the research phase.
That way, you’ll have easy access to every bit of information you’ve collected when it’s time to sit down and write.
Consult With Subject Matter Experts
Apart from the information that can be collected from internal documents and external resources, crucial knowledge can also be obtained from the valuable team members who developed the product.
These are called subject matter experts (SMEs), and extracting knowledge from them is an essential part of technical writing.
Writers contact and/or meet with experts daily to get answers to their questions about the product, follow up on information, and obtain accuracy reviews for their documentation.
The format for the collaboration between writers and SMEs is usually the interview. During their research, writers need comprehensive information about how the product works, so it’s a good idea to block off time to sit down and get as much information about the product as possible.
The key to a good SME interview is preparation. By the time you’re consulting SMEs, you should already have some first-hand experience with the product and some knowledge from other available resources.
Technical writers claim that the best way to conduct the interview is by asking open-ended questions and allowing the interviewee to do most of the talking. The questions usually revolve around the basic characteristics of the product.
You can record their answers by taking comprehensive notes or recording the interview (especially if it’s a virtual meeting).
Your aim should be to capture every bit of knowledge you need in just one interview, but keep in mind that it’s perfectly fine to follow up on the meeting and ask for further clarification.
Good writers tie up every loose end before sitting down to write. Bad ones get embarrassed about contacting SMEs a second time and opt instead to publish unverified information in their documentation.
Remember, subject matter experts are the people that brought the product you’re documenting into existence. As such, they are the most authoritative source of knowledge about the product and should definitely be consulted during the research phase.
Stay Focused on the Topic
If you followed our advice this far, you should have a wealth of credible information and valuable knowledge at your disposal during the research phase of the documentation process. That’s great, but you should be aware that having too much information can be detrimental to quality research.
That’s because doing too much research and getting bogged down in the details can waste a lot of time and pull you off-topic. That’s not a very efficient approach to research, so here are some tips for staying focused on the topic at hand.
One idea is to take up the practice of mind mapping. Mind maps put your research topic at the center and allow you to brainstorm all the aspects connected to it. This allows you to come up with an exhaustive list of components you need to research and enables you to imagine the relationships between them.
You can use software tools such as Coggle to easily map out your research in visual terms.
So, for example, if you needed to research the API of your product in order to write an API guide, your mind map might contain components such as:
- Installation instructions
- Code examples
- Possible error codes and their solutions
- Use cases
Once you have everything mapped out, you can start researching every component and focus on only the components of your mind map, leaving everything else aside.
Another way to go about this is to use document templates. A template is essentially an outline of your future document, and it already contains the document components that just need to be filled out with specific information.
For example, here’s a template for tech specifications created using Archbee:
By using a template like this, you’ll know exactly which information to research and include in your document, making your effort more concentrated and effective.
Anything that’s not in the template can, once again, be left aside. For instance, a tech specification doesn’t contain any sort of instructions on how to use the product, so you can skip researching product usage for this document.
Where research is concerned, technical writers really can have too much of a good thing. To prevent yourself from getting sidetracked because of too much information, use the advice we outlined above to keep your research focused and on point.
Verify Gathered Information
During your research efforts, you may come across some problematic data that just doesn’t fit into everything you know about the product. Therefore, as a part of the research phase, you’ll need to take extra steps to verify your information and ensure it’s accurate.
The problems with your data may come in one of the following forms:
- Two pieces of information contradicting each other
- Instructions that don’t lead to the expected outcomes
- Information that defies logic
For example, an important step might be missing from the instructions you were given by an SME, which impedes the use of the product.
So, how does information verification work for technical writers?
Well, remember how we said that your first and most reliable source of information is the product itself? This is exactly why.
A lot of information you obtain from SMEs and other resources can be verified within the product. For example, if your SME has given you instructions on how to install the product, your first action after the interview should be to test those instructions out exactly as they were given.
If following the instructions produces the desired outcome (successful installation), then the information you’ve been given can be considered accurate and verified. If not, you’ll need to follow up with your SME and ask for clarification.
If the information cannot be verified by using the product or checking with SMEs, there are still some steps you can take to ensure the data is correct.
For example, you can check to see if the version of the document you’re looking at is the last one.
This is especially important in technical writing for software because the product will go through multiple phases of development (or versions) before it’s ready to launch, so the information might change rapidly.
Finally, depending on how the documentation at your company is created, you might also be able to look up the author and contributors of the document and decide if the information comes from a trustworthy source.
Quality documentation software usually comes with this feature. Here’s how it looks in Archbee. Just hover your mouse over the icon of the author at the bottom of the page.
Working with verified information is paramount for quality research. If you notice anything problematic about the data you’ve collected, make sure you’ve verified the information before including it in the final draft of the documentation.
Conclusion
Technical writers need access to credible, verified, and relevant information if they are to create technical documentation of the same character.
This kind of information can only be obtained through meticulous research that includes identifying the right questions and topics, as well as the right resources.
In this article, we’ve given you six tips for gathering quality information and consuming it in an effective and time-efficient way.
By implementing our tips into your research methods, you’ll be able to arm yourself with the best available information and write documentation that will never fail to help your end-users.
‍
