Effective documentation requires genuine partnership, not just good questions. Here’s how to earn trust and respect, manage time constraints, and create content that actually serves users.
The relationship between a technical writer and a subject matter expert (SME)is critical for effective documentation. When this partnership works, the result is clear, accurate, and user-friendly content. When it fails, documentation can suffer and end up frustrating all involved. The key isn’t about asking good questions; it’s about building a relationship based on respect, preparation, and shared goals.
Do Your Homework First
SMEs never have enough time. Respecting the time they do have is the quickest way to earn trust and cooperation. Do the homework first. This not only saves the SME time but also allows you to ask more intelligent, specific questions.
Start by learning the product. Use the product yourself. Click every button, explore every menu, and try to perform the user tasks as a naive user. Read all existing materials, including previous documentation, design specifications, user stories in project management tools like Jira, and any marketing materials. Don’t be afraid to look at the source of truth. This could be code comments or commit messages in a Git repository. Review the Jira tickets to understand what was done, how it was done, and why. Use your own resources first so that when you finally do ask for help, it’s for something you couldn’t find on your own. This makes the conversation more productive. “I see the system is designed to add products, but I haven’t seen where I can add products at another warehouse. Can you walk me through it?” is much better than “How do I do this?”
Asking Is an Art
How you approach the SME is crucial. Developers often work in a flow state of deep focus. Interruptions can hurt their productivity. Therefore, your communication method and style matter.
First, batch your questions. Instead of sending a constant stream of messages throughout the day, compile your non-urgent queries into a single, organized list. A well-structured email or a short, scheduled meeting is far less disruptive than a dozen random pings on Slack.
Second, choose the right channel for the right question.
- Instant Message (e.g., Slack, Teams): Ideal for a quick, simple question that needs a yes/no answer or can be resolved in a sentence or two. Example: “Just confirming, is the character limit for the Contact Name field 255?”
- Email: Best for your batched list of more detailed questions that require thoughtful answers but not necessarily a real-time conversation.
- Meeting/Call: Reserve these for complex topics, live demos, or brainstorming sessions where back-and-forth discussion is essential. And always go into a meeting with a clear agenda and specific goals.
Third, and most importantly, make it easy for them to help you. Never ask a vague question. Don’t ask “Can you explain the new API to me?” This puts the entire burden on the SME. Instead, take that question and expand on it. What is the API for? What are the endpoints? Are there examples I can experiment with? Make a list of user tasks that you need clarity on and use that when asking for help. Always try to provide context, and if possible, show your work. A much better question would be: “I’m documenting the /customer/{id} endpoint. My draft explains that it returns the customer name and email. Can you confirm if any other data fields are returned and provide the specific error codes for an invalid id?” By including a link to your draft or a screenshot, you give them a concrete starting point to react to, making the review process faster and more efficient.
Remember, “I don’t know” is a complete sentence. There’s no shame in admitting you don’t understand and that you need help.
Perfecting the Review Cycle
Technical reviews are critical. But a document sent without proper instructions and guidance isn’t helpful to the reviewer. To ensure a smooth review process, set clear expectations. When you share the document, be explicit about the kind of feedback you need. Are you asking them to check for technical accuracy only? What about the clarity of the explanations? Are the code examples accurate, correctly commented, and good real-world examples? It’s also a good idea to tell reviewers what they can ignore, such as formatting, fonts, etc. You want the document to be technically accurate, and that’s the purpose of the review. Provide a deadline to help them prioritize the task.
Guide their review by leaving specific questions in the comments. For example, instead of hoping they’ll notice a potentially confusing section, add a comment like, “Does this analogy about caching make sense, or is there a more accurate way to explain it for a non-technical audience?” This directs their attention and encourages the precise feedback you need.
Don’t take feedback personally. Reviewers ensure technical precision, while your job is to advocate for the user’s understanding. Sometimes, these goals conflict. View their edits and suggestions not as criticism, but as a crucial part of the collaborative process to find the best possible explanation. Remember, your user may want to know what time it is, but doesn’t need (or want) to build a clock. I
Build a Partnership, Not a Transaction
It’s more effective to build a lasting partnership with the team than to just show up to extract information. Be an ally who helps make their hard work accessible and understandable to the outside world. Remind them that the documentation can reduce the support burden on their team. Every question your document answers is one less support ticket they must handle.
Show your appreciation. Thank people for their time and effort. Give them credit in status reports or let their manager know about their contributions. By closing the loop and showing them the final, published work they helped create, you validate their effort and make them more willing to assist you in the future. Hold brainstorming sessions with developers to share your plans and gather their insights on how to improve them. Your goal should be to transform the dynamic from a one-way street of questions into a two-way partnership with a shared goal: delivering a successful product.