What SMEs wish tech writers knew

Tech writers turn complexity into clarity – but not without the SME’s critical eye. Understanding what drives our experts paves the way for smooth collaboration.

Text by Saul Carliner Nicoletta A. Bleiel

Inhaltsübersicht

Image: © SACheckley/istockphoto.com

Picture the following scenario:

Manufacturing engineer Kurt gives technical communicator Saska a tour of the manufacturing line, whose process she is documenting. Saska diligently takes notes on her iPad and is surprised when Kurt says that he would write everything down for her. Saska comments that while she appreciates Kurt’s offer, it is not necessary: “Documenting the process is my job,” she says and goes on to explain that the company paid her to document the process as well as to provide additional detail that would help workers perform the process safely, productively, and without errors, not to mention developing and implementing a style guide, a publishing and review process, and following proper accessibility and other guidelines.

Kurt is surprised. He had considered this to be his job.

The bottom line of this anecdote? Subject Matter Experts (SMEs) clearly play an important role in the design and development of technical content. However, sometimes confusion arises around the roles of SMEs and tech writers when developing technical documentation. And this leads to tension between the two parties.

Building on the general advice offered in our previous articles, “Strategies for interviewing Subject Matter Experts” by Nicoletta A. Bleiel, and the specific advice for addressing some of the more common challenges that arise in this relationship in “Five common challenges in technical reviews and how to address them” by Saul Carliner, this third article in the series focuses on the SME’s perspective, and offers five insights into underlying reasons for the challenges in the relationship between SMEs and technical communicators.
  

Insight 1: SMEs have other jobs

When in the midst of looming publishing deadlines, one can easily forget that SMEs’ primary role is not reviewing documentation drafts, but applying their technical expertise as programmers, engineers, scientists, product managers, legal experts, and similar roles. Those jobs have their own primary responsibilities. Programmers, for example, are responsible for producing working code for part or all of a software application. Product managers are responsible for responding to market research by proposing new products, providing oversight to the design and manufacture of those products, and ensuring their success in the market.

They all face different challenges. Consider, for example, the quality assurance engineer, who is expected to review technical documentation drafts while at the same time the product is failing its quality assurance tests. These failures add complexity – and hours – to their work, leaving less time to review the documentation.

Reviewing documentation for accuracy is undoubtedly their duty, but only one of many. Other tasks might consume their attention, especially when “fires” ignite, such as failed QA tests. With that in mind, tech writers need to make an effort to set reminders for SMEs. This can be a challenge, even when we have defined clear review processes and deadlines.

yes When dealing with limited capacities, specify your questions and review requests in job tickets to help SMEs manage their workloads and speed reviews along, while documenting the status of the knowledge gathering and review in detail.
  

Insight 2: SMEs have a viewpoint that substantially differs from the users’

Although most SMEs have a good sense of products and services and their intended use, others lack awareness of how people use their products or apply their solutions. For example, a programmer might work on a particular module of a software application whose work remains hidden from users, or a researcher might generate statistics on an engineering project but have no idea of the purpose of the project. SMEs who have partial views of products and projects can provide insights into whether a statement related to their work is accurate, but not how this statement reflects how people use the feature.

Additionally, SMEs might lack awareness of different groups of users. Consider the use of word processors by students, who use word processing to prepare reports and essays with references, tables, and figures; professional authors, who produce lengthy documents with headers, tables of contents, indexes, and other elements; and consumers, who use word processing to write formal letters to organizations regarding purchases and personal issues. Like tech writers, many SMEs lack direct access to their users and, as a result, lack awareness of their users’ requirements.

Consider the tech writer whose programmer tells her that the primary markets for the timekeeping software application she is documenting are hospitals and factories, both of which have hourly rosters. Later, the product management and marketing teams – who have more direct access to users and market research – tell her that the primary markets are factories and universities, which use the software to track their numerous part-time workers.

yes Although no single strategy works when dealing with SMEs who lack direct insights into user behavior, there are strategies to help develop awareness. Presenting data and personas on users developed by the user UX team, or asking SMEs to walk through a procedure as a user would experience it, can help SMEs gain empathy for users.   
  

Insight 3: Organizational culture shapes the self-perceptions of SMEs

Different organizations give SMEs different types of “rights” over documentation. In some cases, SMEs have “reviewer rights”, meaning that it is their job to review documentation, and technical communicators need to consider their comments when revising the material. In other cases, SMEs have “ownership rights”, meaning they not only review documentation but can also insist that technical communicators incorporate their comments before approving to publish.

In some cases, SMEs with reviewer rights act as if they have ownership rights.

Consider the engineer who did not agree with the tech writer’s approach to describing a report. While the tech writer was on vacation, the SME insisted that the department manager give the SME access to the draft and rewrote it to his own liking.  The manager later had to apologize to the technical communicator when realizing that she let the SME overstep his authority.

yes To clarify the ownership rights of SMEs on a project, speak with your manager before starting it. Confirm the ownership and review rights SMEs have at that time. For example, can the SME prevent the project from moving forward or dictate how information is presented to users?
  

Insight 4: Organizational structure leads to conflicting views among SMEs

Many of the products and projects on which technical communicators work are complex, involving large numbers of specialists. A complex software application can involve programmers, user experience experts (other than technical communicators), quality assurance specialists, marketing experts, and legal experts, among others. Each specialist has their own job with its own focus. Furthermore, when several people from the same team work on a project, they divide and conquer, with each person focusing on just a small piece of work, which can result in a lack of communication.

This is why, as noted earlier, SMEs sometimes do not have full oversight of the projects on which tech writers are working, and this means that SMEs sometimes have different and conflicting visions of the product or project and might not even realize this. SMEs might only become aware of alternate views of a product or project when reading the first draft of the documentation. Tech writers might inadvertently surface these different perspectives and then face the challenge and responsibility to address them.

yes When SMEs have competing views, the best option is to bring them together to discuss their differences and reach a consensus on how to move forward. Ideally, a neutral third party can facilitate that meeting to minimize the likelihood of conflict. If that is not feasible, ask a manager who has responsibility for all the groups that share differing views to help work out a resolution.

If your company holds regular face-to-face company meetings, those events provide another opportunity to build consensus among SMEs. Request a time slot for an SME meeting and get it on the schedule. Make sure to put together an agenda so that the meeting has structure and no discussion points are missed. As mentioned earlier, presenting user personas can also be helpful, and could be the ideal place to start the discussion. Come prepared with examples of scenarios where there have been differing viewpoints, and propose a solution for each. It's a great way to frame a discussion. Another option is to start with a single question (for example, "What is the most common use case for this feature?") and have everyone answer it.
  

Insight 5: SMEs do not know their responsibilities

Most SMEs recognize the importance of their contribution to the documentation, even if that effort is invisible to users. However, some SMEs don’t know what is expected of them and don’t know how to contribute to the effort. In some cases, SMEs lack insight into what to focus on when reviewing draft documents and which parts can be safely skipped. Some SMEs unnecessarily take on the role of copy editor, when their technical expertise is needed to confirm that the content is technically accurate.

In other cases, the SME might not understand the role of the tech writer, assuming that technical communicators simply “wordsmith” text that SMEs draft.

yes Tech writers have a few options to clarify the role of an SME:

  • Provide materials that orient new SMEs to their role in the review process. Although these written or video materials need to be brief, they can:
    • Describe the role of the SME in the documentation process
    • Describe the review process
    • Provide examples of more helpful versus less helpful comments
    • Point out what they should focus on and what they can avoid

Technical communicators can post these materials on their company’s internal wikis or collaboration platforms.

  • State the role of the SME in the review process in the cover letter (in the email or job ticket) that accompanies review drafts (e.g., to assure technical accuracy), and provide some guiding questions to focus the review. Remind SMEs that editorial and usability experts will also review the material for readability. Tech doc teams might prepare templates for such letters to ensure they cover all the necessary details. Consider producing several versions of these materials; the differences will make SMEs pay closer attention to the cover letter when receiving drafts to review.       

Make sure that you are clear on responsibilities. Some technical communicators make the incorrect assumption that SMEs should provide a comprehensive set of content to include in the documentation (that is, write most of the documentation). This is not only an unrealistic expectation because of the insights we’ve already discussed, but it can also result in incomplete documentation.

Developing deep expertise about an application and communicating this clearly, accurately, and in a way that aligns with users’ contexts and needs is the special value that technical communicators add. SMEs have an important role in helping technical communicators to do so.
  

Working effectively with SMEs

The potential challenges when working with SMEs listed here (and no doubt others we didn’t have space to raise) affect their contributions to and review of technical documentation.

Bear in mind that SMEs have other responsibilities and different perspectives on the subject, which might substantially differ from users’ needs. Organizational structures might affect the perception of their roles as well as their views of the subject. Some SMEs might not even fully understand their responsibilities when it comes to reviewing documentation.

To work effectively with SMEs, technical communicators need to develop an awareness of the SMEs’ roles and responsibilities, and develop empathy for the challenges that they face.