A coffee table write-up for a Subject Matter Expert
– Deepa Gopalakrishnan
I am trying to finish that last section in my document. After the eighth revision of a segment of text over the past releases, someone in the team thought that the following piece of input would help me seal the document for the product release next week.
When you analyze the cycle time of one object the aggregation rule used is average which provides the right values for the user signing off on many objects. I immediately thought of: Betty bought a bit of butter, the butter was bitter; Betty bought some better butter to make the bitter butter better.
This may be a correct sentence, but it does not make sense to me when I am sincerely attempting to chase a release timeline. The aforementioned, (seemingly) pointless piece of supposedly sensible text (You didn’t think, I would be affected so much by the tongue twister run-on sentence, did you?) is available as a reliable live document somewhere on the Internet. I have edited the original text to the less-confusing tongue-twister that you just read, for this article.
This is not the first time I received a pointless piece of input from the development team. Every time, I have had to take help to resolve the input issues and then proceed with my work on it. It makes me think that there is something missing; else no one would send such seemingly pointless input.
A little introspection and a rewind of sequences from my years of experience as a technical writer, revealed a patterned behavior in most developers. The basic fact that some developers have no idea about what inputs to give and what to expect of a user document is the primary cause of such inputs.
Other causes as I see are:
- Excess information
- Insufficient information
- Disparate information
- Lack of clarity
- Inability to explain
- Inability to communicate
We, as writers could help the developers or the Subject Matter Experts (SME) help us better by letting them know what we expect during a Knowledge Transfer (KT) session.
Let’s start off with a basic definition of Knowledge Transfer. The SME explains the concept to the writer. This is called Knowledge Transfer.
The popular modes of a KT are as follows:
In this mode of KT, the writer meets the SME and discusses the new feature or update that has gone into the product. We must ensure that our SMEs know the following basics before they start off with the project. This section is addressed to the SME.
- Fix appointments for the KT.
- Schedule your session.
- Circulate the related documents if any, prior to the KT session.
- Be available at the appointed hour for the discussion.
- Understand the purpose of the document.
- Be ready to answer doubts.
- Set aside time in your calendar for the review of the document.
- Do not schedule KTs when you have an important meeting coming up. You may not be able to devote your mind to the KT completely.
- Do not explain more than you or the writer can handle at a time. The topic may not be covered exhaustively.
- Do not force your mind to think of the subject matter when it is busy with other thoughts. You may lose focus on important points.
Nice to know
- Capacity to understand differs from person to person.
- Your state of mind on the date of discussion drives your discussion.
- It is perfectly acceptable to postpone the appointment when you are not clear about the concept.
In this mode of KT, the writer receives inputs about a topic as document attachments, emails, and web reference links. We must ensure that our SMEs who send such inputs, know the following basics before they click that ‘Send’ button. This section is addressed to the SME.
- Always verify if the material makes sense to you.
- In your email to the writer, specify if the material is elaborate or just about right, as you see it.
- If you send a segment of text taken from an existing document as input, specify the source of the material.
- Verify if you are sending material taken from the latest version of the reference document. For example, if you are referring a document written in 2004, and the next update of the document was written in 2008, then the 2004 reference may be incorrect.
- Allot time to review the content that is rephrased or collated from the segment of text that you send.
- Discuss your written input if need be.
- Do not expect a copy-paste from the write-up you sent.
- Do not write all you know about the subject.
- Do not deviate from the purpose of the write-up.
- Do not give numerous references to other documents for a given segment of text.
- Do not give ambiguous statements as inputs.
Nice to know
- The input that you give may be incorrect.
- You may miss out an important point.
- Your writer may understand a written input differently from its intended context and meaning.
- No document is perfect; so is your input.
You can give the following guidelines to the SME to provide inputs or ensure that you have answers to all these points before you start writing your content.
General idea about the subject of discussion.
Background of the topic and its importance.
Examples, illustrations, diagrams, or screenshots.
Related prerequisites such as settings or parameters.
- Field explanations
- Steps or procedures
- Alternate methods
- Possible errors
- Important notes
- Best Practices
- Other points
Related areas of impact
As technical writers, if we are able to convey these points to the Subject Matter Experts, then we can minimize last minute hassles related to Knowledge Transfer and help ourselves do a better job.
About the author:
Deepa Gopalakrishnan is an engineer and holds a senior technical writer’s position in Oracle India, Bangalore. She has 6 years of technical writing experience in product development companies and most of her work experience involves technical writing for application software.