To view this article in PDF format, click click here.
Getting the Information You Need from SMEs
Your deadline is a few days away, you have several manuals that have to be completed, you are hopelessly behind in your schedule and your subject matter experts (SMEs) are too busy and don’t have the time to sit with you and help you. What do you do?
If this situation sounds familiar, then this article may be for you.
One of the standard questions asked of most technical writers during a job interview, is what do you do if you have a problem getting information from an SME or meeting a deadline? This may be one of the most common problems encountered by technical writers.
The answer to this question is not simply a matter of your personality or the strategies you normally use in dealing with problems. It also requires an in-depth understanding of the documentation cycle, i.e., how documents get produced in a normal IT or software company and the processes and people involved. Understanding the documentation cycle and your role in it will help you to clarify the strategy necessary in solving any specific problem related to your work.
Documentation can be seen as an import component of the product. The code and hardware components of the product provide the functionality of the product. The inner workings of the code and hardware are usually not accessible to the end user. The product documentation fills in this gap, by describing the product and how to use it. It should be considered as an integral part of the product. Documentation is usually written around a specific product release and is released together with the product on the same date.
In the typical IT company, the usual “owner” of the production process is the product manager. The product manager is responsible for determining the features of the product and setting target dates for its development and release. This includes the documentation that is shipped with a release.
The product manager works with the technical publications manager or a technical writer to define the schedule for the release of the documentation and the list of required documents for a product, including the features that each document is going to cover.
To get a successful document out of the door requires the combined efforts of an entire team of experts. The criteria for ‘success’ is usually a combination or reliability, comprehensiveness and ease of use, leading to customer satisfaction with the end result.
As a general guide, the following departments may typically be involved in the production of end user documentation:
The concept of the single “author” of a document is erroneous in the context of the typical IT company document. This concept may be hard for some technical writers to accept, since they see their role in the company as “authors” of documents. In this misconception lies the heart of the problems that many technical writers complain of. The question “what do you do if you can’t get information from a SME in time?” is actually misleading, since it places the technical author at the center of this process and implies that he/she is the sole owner of it.
It is essential therefore to clarify your role in the process with the other professional members in the team, making sure that your expectations are on par with those of other members in the team.
The role of the technical writer is that of a “service provider”, providing a service to other departments in the company. The writer does not initiate the process of production or manage it in any way, he/she simply provides a value-added service to the manager of the process – usually the product manager. As a service provider, you should be in constant contact with the real owner of the product, informing him of any problems in delivery well before they occur.
So what do you do if you can’t get information from a SME in time?
If you are an industrious and conscientious worker, then it is most likely that the problem lies in the review and production process and not with you. In this case, you should turn to the Director of Quality Control.
This is a little understood role within the company framework, although its function is extremely important to the healthy operation of the company. The Director of Quality Control may go under a different name in your company. Their basic role is to define workflows for and between various company departments, to ensure that operations work smoothly and products get produced on time. Usually, they’ll produce a list of flow-charts, describing the complex interactions between different members in the company. If you haven’t already done it, at some stage you should sit together with the director of quality control and any other departments who are involved with the production of documentation, and work out the flow procedure of who is responsible at what stage and for what.
The review cycle is the tool that technical writers use to gather feedback on their draft versions. Ideally, this should be an automated database system, such as Lotus Notes, which allows you to add a new document to the database and set up a review cycle – including deadlines for reviewing the document. The review cycle database should be able to record all aspects of the review:
The review cycle enables you to keep control over the development of the document. Presumably, you will have agreed with the product manager on a timetable for submitting draft versions for review and receiving feedback.
If for whatever reason, either you or an SME misses a deadline due to factors beyond your control (this could be a sudden illness or travel requirements or the intrusion of another project which takes priority), then the product manager should be informed. If the problem is under your control, or your responsibility, you should provide an alternative means for completing the deadline (either outsourcing work, so that you will have more time free for this project, enlisting the aid of another technical writer in your company, if one is available, or requesting additional help and time from the SME).
If you have requested a review or a meeting from an SME, and he/she is not forthcoming or helpful, making it difficult for you to get the information that you need, there are a number of things that you can do, but you should remember that you are not the manager of the SME and are not responsible for setting his schedule or priorities.
Before turning to the project manager or product manager with a problem, it is a good idea to clarify with the SME the reason for the delay or difficulty. Is it simply that the SME just doesn’t have the time, because of other project commitments, or do you feel that it is a problem of attitude – your role and contribution is not respected or appreciated?
Too often, technical writers have the tendency to jump to the latter conclusion. However, do take the time to clarify the SMEs point of view.
Getting to know the employees in your company, including SME, and establishing friendships is an important component of your day-to-day working environment. It is just as much a factor in your success in the company as your technical writing skills. A friendly and positive attitude towards those you are working with or see on a day-to-day basis helps create a pleasant, non-threatening environment in which to work.
An approach that is friendly, considerate and respectful towards others will in turn earn you respect and consideration. There are several ways to build up relationships with your colleagues:
When you run into problems, there should be one or two friendly ears you can turn to and let off steam if needs be, without having to turn to official channels.
If you have established a reputation for yourself in the company as a friendly and professional person, you should find that SMEs are in general willing to be helpful. However, if you find that SMEs are consistently stonewalling you, before hurling your frustration at them, ask yourself what could have caused their stonewalling? It may have something to do with how you are informally perceived within the company.
Unfortunately, power plays and positioning may be a reality in the company that you are working for. This may come to the fore at times of uncertainty and change within the company, or when new department heads are hired and their strategy or management style is not accepted by the older, more established employees. When this happens, then various interest groups within the company may have a tacit, implicit agenda to undermine the activities of other interest groups. This is usually manifested in disagreements about the roles of various teams or the general strategies being followed.
A situation where various departments are not completely cooperating with each other or are openly critical of each other can impede the free flow of information and the workflow within the company, and you, as the technical writer, are likely to be affected by it. So what do you do?
Perhaps the best strategy is to focus on the task at hand and avoid taking sides. Be neutral and professional in your approach to all teams (including your own). If you run into a dead end with one resource or person, try another avenue for obtaining the same information. There should be a level of redundancy built into the company so that no single person is the only source of information on a component of a product.
The following strategies can help in organizing your schedule so as to make the maximum use of your time and avoid problems:
After you have completed a project – especially one in which problems arose – it is important to review the entire process, to identify the weak links and find ways to improve the situation in the future. Otherwise you may find the same thing happening again the next time round.
To understand how the “theoretical” process outlined above might work out in practice, I’ve chosen to illustrate with an example.
John, the product manager for “Pegasus”, a new project, based on a previous product that is to be customized with a specific group of customers in mind, gets in touch with you to arrange a meeting to discuss the project. You have worked with John on a previous project and have been to lunch with him a few times and have a good working relationship.
During the first meeting, between you, John and the project manager, John describes the nature of the project and the documentation he thinks is needed. The project manager supplies some extra technical details, including the names of the engineers working on the team and their area of specialization. You ask where you can find any available written information on the project and ask questions about the project to clarify the target audience and the documentation needs. John indicates the targeted date for the Pegasus release and you agree upon a set of dates for documentation draft reviews, feedback and final version.
You start to gather information. You set up meetings with the technical engineers, some of whom you already know, and have worked with on previous projects. You arrange for time to be spent using and testing the functionality of the product, if necessary, taking screen grabs of the user interface and checking for any inconsistencies between specifications documents and implementation.
You submit an outline for the document to the project manager and agree upon it. Soon, you have a working draft, which you place in the review cycle, requesting that each engineer review his section of the work.
Once review comments have been gathered and implemented, you can submit an updated draft for review.
To this ideal scenario, we can add a number of problems that could go wrong in the production cycle:
Let’s suppose that George is a new product manager, who you’ve never met, and you are working with a project manager who dislikes you for whatever reason. George is pressured by higher-level management to a customer release date, before the second earnings quarter, that he cannot hope to fulfill. As a result, George, under a lot of pressure, starts shouting at the development team to produce results. When you raise objections to the documentation schedule, he tells you that you’ll just have to work longer hours to make up for it and that the engineers don’t have time to spend with an outsourced writer, who is not familiar with the company’s products.
Your worst nightmares are realized. The project team does not have any time to spend with you, and when you contact them, their general response is irritable and unhelpful. The project and product manager are unhelpful. Everyone is feeling the pressure. The deadline is two weeks away, and you know you’re not going to make it. What do you do?
Here are some strategies you could use in this situation: