Nearly everyone has been in a situation where they they thought they knew exactly what the customer wanted and delivered the “perfect” product only to find that they you were just a little off of the target. If only a few more questions had been asked to gain just a bit more insight into the customer’s needs, then a difficult situation could have been avoided.
In the realm of technical documentation, it is far from pleasant when a document is delivered to a customer and returned with so many redlines and comments that it must be completely rewritten to straighten out. Particularly if your rewrite requires you to ask your client for more money – or worse, you have to re-do the job on your own time.
But The DocuDoctor is here to say that there are ways of preventing a document from becoming rejected and negatively impacting your customer’s confidence in your company’s ability to write an effective and accurate technical document. Those of us experienced with developing complicated and sometimes lengthy documents know that a little advance preparation can go a long way. And, this can be as simple a matter as asking the right questions. Always remember that we are writing our documentation from a position of understanding, and asking questions to those possessing the knowledge is an excellent way to be better informed.
The following is a checklist of items that should be answered prior to beginning virtually any documentation task. In fact, you may want to consider taking a copy of this checklist to your next customer meeting.
_____1) What does the customer state they want in terms of technical documentation? Does he need operating manuals? Parts lists? Instruction manuals? Or, is he trying to fix a knowledge-flow problem with documentation?
_____2) What does he intend to use the documents for? On-the-job training? Field repairs? Technical reference? Classroom instruction? Or, obtain a post-delivery historical account of what was done on his job?
_____3) Who will the documents end-user be? What is the expected education level? Do they have experience with this system?
_____4) How does he want the information structured? Handbooks? On-line help? Study guides? Reference cards?
_____5) What file format does the customer prefer for each document type? Does he use a particular application for developing, storing and deploying his documentation?
_____6) Does the customer have an example of a document that he has used or has seen in the past that he was particularly pleased with? If so, can he give or loan you a copy? What didn’t he like about it? What does he want you to do better or differently?
_____7) How many and what kinds of document reviews does he want? Does he want formal or informal reviews? If formal reviews are requested, is there a possibility of “high-level” customers attending (e.g., Admirals or Generals)? Will the draft document get reviewed in the After Action Review (AAR)?
_____8) How much time does he want to review each document? Can you start work on the next version while awaiting his comments on the draft version? Does the review process include the task managers or contributing engineers?
_____9) Can you establish a standard procedure for receiving and documenting revised or updated information? Can you provide a checklist to his reviewers to ensure all pertinent areas are reviewed and accepted or rejected? If rejected, can you obtain a detailed explanation of what needs to be revised and how?
_____10) Who on the customer team has the responsibility for deciding the final acceptance of the document(s)? Are they most concerned with the document’s content, format, brevity, ease-of-use, or all of the above? How will you know when you have achieved success?
_____11) Does the customer prefer a strong reliance on graphics and illustrations? Can photos or screen captures of the system be taken readily? Will a graphic artist be needed to create representations of the system while operational?
_____12) Does the customer wish to monitor the documentation schedule and progress? If so, does he prefer to have progress reported to him by milestones? If your customer is hands-on, what role will he play, and how much of your time will be required so that he can be “helpful?”
_____13) What constitutes acceptance of your documentation? Will you have the opportunity to perform a validation & verification (V&V) of your documents while hands-on with the system? Will a “user certification” be conducted to verify the content’s accuracy and completeness?
_____14) Should safety issues be addressed in the documents? What is the customer’s required procedure for documenting ‘critical’ items or special aspects of the system? Is there an applicable specification that dictates required attibutes for hazardous or adverse events?
_____15) How closely will the documentation schedule follow the design schedule? Will the engineers have time to participate in the documentation process, or will the technical writers be discreetly shadowing the engineers?
_____16) Does your customer have any unusual requirements like travel to a distant location, or requirements that could change from day to day?
Although some of these items may seem obvious or may not be relevant to your particular project, many of them will help enhance the understanding that you have of your customer’s needs and show your customer that you are on top of the documentation aspects as well. Although technical writing is a supporting function to the engineering design and development of the system, it should be accomplished as an active part of the system’s development lifecycle. Know your customer’s expectations for the product, be familiar with the development environment, and have clear goals for the documentation product you are expected to develop and deliver.
Meta-Systems Documentation, Inc.
All Rights Reserved