What questions do you ask to SMEs to begin with technical documentation?

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…

Published by

Suyog Ketkar

He is a certified technical communicator. He believes that writing continues to be an easy-to-do but difficult-to-master job. In his work time, he proudly dons the “enabler” cape. In his non-work time, he dons many hats including one of a super-busy father.

6 thoughts on “What questions do you ask to SMEs to begin with technical documentation?”

  1. I’d also look at QA test cases and any implementation data. Case analytics from support (if available) are also invaluable on what topics need to be covered and in how much detail.

    Like

  2. Three important points for me:

    (A) For “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 mean that the SME decides or proposes what all deliverables (or content types) a technical writer needs to develop? If yes, on what basis? What is the process and how an SME is qualified to make ‘this’ decision on what all deliverables are required? Was there a user research stage and is the documentation team involved in that user research process? I have same comment for “Do you require a knowledge base?”.

    (B) Where is the style guide (for authoring, and for voice and tone)? How a technical writer ensures that the authoring style maps with other content-specific roles in the organization including copywriters, content marketers, or customer support team?

    (C) How do you measure the effectiveness of documents? For example, if Google Analytics are integrated, is there a process to define measurable goals of documentation?

    Like

    1. All valid questions, Vinish. First, thank you for the comment. I’ll take up your questions one by one.

      (A) As far as my current organization is concerned, it is the SMEs who decide what document or documentation format circulates to customers. It appears that the SMEs expectations were based on requests from customers and consultants. I know that this might not have been the correct method of deciding on the deliverables, but this is how we handled it here.

      Also, an SME may not be the right person for this question. But, they certainly are relatively closer to the customers, so they have a natural edge against us on that. That’s still debatable. In the end, I believe, it all boils down to the project deadline and plausible efforts within that time. What’s your opinion on it? Knowledge base, per se, was never a part of our efforts until recently. And, after knowing how effective the KB cases are in reducing the workloads off the consultant’s shoulders, everyone seems to be talking about it in the company.

      (B) We follow MSTP. So, no change to that. Except, maybe, the internal style guide. But, that’s still no question, because we periodically discuss about possible changes in the internal style guide. Every tech writer adheres to the internal style guide along with the MSTP. Here, content writers and copywriters do not follow a style guide, though, they do put in efforts to keep the voice, tone, and structure consistent across all marketing collaterals. But then the issue is not with the style guide, but with the work allocation. Like us, they follow document-based ownership. Also, since this factor is known to us, I don’t think we will pop this up to the SMEs as a question.

      (C) I have not used any tools that can help me measure the effectiveness of documentation. I crosscheck the document based on how quickly can I find a topic and how easily can I follow and use the documented information. Maybe you can help me understand more about the tools.

      Like

  3. (A) For SME making a call on deliverables, I am not too comfortable unless technical communicator is part of the decision making process. At the same time, it depends on who the SME is – in what role and with what experience. Two, if SME arrives at such a decision after a user-research process, it can be acceptable but as I said, communicator too should be part of that user-research activity.

    (B) MSTP is good only for reference in core instructions. Otherwise, I am not a fan of such conventional style guides. These worked better when the documentation was confined to PDF, CHM, or embedded assistance. When organizations are opening arms for say, user generated content, documentation cannot stay compliant to MSTP. Two, assume that a marketer is referring to product features in a product sheet, or in a technical blog post. It is important to ensure that everybody in the organization (marketers, communicators, customer support) are using same vocabulary in technical content. Another reason, of why I don’t really favor MSTP as we get it.

    (C) Analytics over a period of time give us an idea of what topics are most/least referred to by the customers. Food for thought for product team and communicators. Google analytics helps, many HATs and CMS too offer their own analytics tools.

    Like

    1. I agree that every document/communicator in a company should adopt the same vocabulary. In fact, that is perhaps why I see increasing number tech writers contributing efforts into creative-writing teams. In our company, at least as of now, we do not generate content beyond the rather conventional PDFs and CHMs (for product documentation) and blogs and white papers (for marketing purposes). Besides, writers like me, keep getting tasks that relate to both technical writing and content writing.

      I have a take on your opinion about MSTP, which you might find intriguing. MSTP is “conventional” because almost all companies into software product documentation follow it, and not because it deals with the conventional use of the English language. Also, the latest edition is a lot “friendlier” in the sense that it replaces the “Correct” and “Incorrect” usages with the “Microsoft” and “Not Microsoft” usages. This in itself registers the shift of opinion toward a user-friendly writing style. This still does not count as a question to SMEs.

      It is perhaps too generic to say if an article, which is relatively more referred to than the other, will contain more accurate information. That’s because such an analysis will still not tell anything about the quality of the document. As of now, I will stick to my way of crosschecking my documents for information findability, and still not toss a question about it to the SMEs.

      Like

Comments are closed.