The Technical Writers Checklist

If you’ve read the previous newsletters, you now know the following: We thoroughly understand the task at hand. We’ve hired the right people. We’ve identified a Documentation Consultant to help us over the rough spots. And we’ve established our budgeting and schedule. NOW LET’S WRITE SOME DOCUMENTS!

As always, we will be working under the assumption that our customer, client, or employer desires a top-quality document and has the money to finance it. So, with that being understood, we need to look at some of the tasks the technical writers should identify and accomplish in building a technical document.

The first and most important aspect in writing a document is to become fairly familiar system to be documented. How does one become as knowledgeable as a ‘user’ without spending 10 years in the field? ASK QUESTIONS! And always take notes. The first checklist (#1 below) applies to any documentation team-member responsible for the document’s content. Certainly, the actual leg-work can be delegated to a junior member. So, let’s begin by gathering the data.

1) Obtaining the technical data (borrow, copy, or request what you need)

_____ Obtain a copy of the technical proposal and project plan submitted by your employer to the customer. Also, obtain a copy of the customer’s initial Statement of Work (SOW). Note any significant differences between them and get clarification.

_____ Obtain and review any existing documents from previous or similar versions of the system. These may be obtained from the customer, your employer, a peer, or your own archives. Find out what the customer likes and dislikes about these documents.

_____ Obtain any manuals, handbooks, correspondence or personal notes that may exist addressing the operational and functional capabilities of the system or product. These are commonly obtained from the operators, end-users, or customers.

_____ Obtain and compile any graphics, drawings, images, sketches, or the engineering drawing package. (For a software application, a book of compiled ‘screen snaps’ or bitmap images can prove very useful).

_____ Attend as many design meetings, discussions, and reviews as you can tolerate. Get your name added to the invitees list. And be sure to get a copy of any viewgraphs, handouts, slides, and meeting minutes that may be distributed.

_____ Obtain copies (preferably current) of any specifications and style-guides that you must follow for format, content, and writing style.

_____ Obtain printouts of the business and process models, and the entity-relationship (E-R) diagram. But only if they will help you understand the system that you are documenting.

_____ Establish methods for obtaining and reviewing relevant technical data. Make it easy for people to give you the information you’ve asked for. Corporate E-mail and common network directories facilitate a free exchange of information. Make sure that your name is on everyone else’s distribution list.

Now that we have all the technical information we could possibly want, let’s decide what we will do with it. As we discussed in an earlier newsletter, the Documentation Consultant has a fair idea of what the customer needs so this may be a good time to consider his/her services. He/She may be able to look at your accumulated data and determine what information should be kept or discarded, or what is still needed. Let’s now put the information that we do have into a more useful and meaningful form.

2) Develop the approach to developing the documents

_____ Draw or sketch flowcharts of the system’s functionality and the user’s workflow processes. Flowcharts can also illustrate design processes, screen sequences, or troubleshooting procedures. (Flowcharts are invaluable in determining the importance of information and it’s order of presentation in the document.)

_____ Revisit the specifications and style-guides you obtained above to refine your objectives for the document(s).

_____ Organize the obtained information into separate folders (or piles if you are the messy type) organized by importance to the customer. Also, identify the information that supports the objective(s) of your document(s).

_____ Make a pass through the folders (or piles) to thin the information down to what is most relevant and important. Your objective for this document is conciseness and clarity and NOT an inflated page count!

_____ Meet with all players on the documentation team to discuss the information you have and what you would like to do with it (be nice!). Should all of the information be included in the current document, or should it be used to develop a document addressing another aspect of the system?

_____ Make the assignments for the documentation staff and establish the task and personnel milestones (and don’t forget to stick to them).

_____ Organize your CURRENTLY available data into categories and sub-categories for inclusion into the outline. Try to limit your main topics to between five and 10. Of course, this will vary for different types of documents and systems.

_____ Give everyone on your team a chance to review and ‘digest’ the technical information then call another meeting! This time, however, you’re going to develop the outline for the document. (Use of a whiteboard is highly recommended for brain-storming sessions like this. Write the purpose of your document at the top.)

Okay, now you have your outline and everyone has a pretty clear idea of where this document is heading. If you are the boss, your subordinates should have your instructions and comfortably understand their respective tasks. The next phase is to begin pulling together the developing pieces of the document into a recognizable form.

3) Begin building the document

_____ Start populating the draft outline with the available data. Make notice of the areas that are lacking data as well as the areas that have an overabundance.

_____ Develop the document’s format such as headers, footers, styles, and templates. Ensure that these match any requirements stated in the SOW.

_____ Schedule and attend periodic reviews of the system and technical data with the engineering staff. Present the information that you believe to be factual and solicit comments from your tech experts. ASK MORE QUESTIONS!

_____ Build tables itemizing and describing data that supports the document’s purpose. This could include report formats, system configurations, selectable menu options, parts lists, rack elevations, and system components. If its relevant to your system, put it in a table where it can be readily seen and not lost in a wordy paragraph.

_____ Schedule weekly document review periods to assess the document’s progress and discuss any problems encountered. Attendees should include members of the documentation team, technical staff, and end-users.

Now comes the moment(s) of truth! Everyone has seen your evolving document and has had ample opportunity to give you their best comments. Now it is up to you to determine which comments are ‘keepers’ and which you ‘throw back’.

4) Let’s finalize that document

_____ Review the red-lines and comments that you have received from your peers, reviewers, customers, and end-users. Do they all make sense to you? Do comments from different people contradict? If so, let the boss make the final decision.

_____ If you are writing procedures for the system’s users or for testing purposes, make another pass through the procedures. Even a 2nd or 3rd pass would not be undesirable. Perhaps your junior writer or admin person could find flaws in your procedures that you (by now, a system expert) may have missed. DON’T UNDERESTIMATE THE IMPORTANCE OF THIS STEP!

_____ Find a quiet room and read through your own document. Check your page numbers, the TOC, the cross-references, your graphics and art-work, footnotes, indices, and anything else auto-generated by your desktop publisher.

_____ Now that you are sure (well, pretty sure) that what you have in your document is accurate, disseminate some copies to your bosses and managers or any other internal authority. You’ll be amazed at what your superiors have to add to your document.

_____ Get the names and addresses of the recipients of your document BEFORE the final delivery day. This is sometimes found in the Statement Of Work (SOW). How many copies does each recipient get?

_____ Print and bind the final document. And always plan for last-minute catastrophes (i.e., toner cartridge runs out, binding machine breaks, secretary forgot to order paper). Print at least five extra copies to hand out to visiting dignitaries, potential customers, and the proud engineers that developed the system.

_____ Now that your document is completed and the kudos are flowing like wine, don’t forget to DELIVER THE DOCUMENTS! And by whatever means is appropriate: FedEx, Internet, Intranet, or Sneakernet