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 (see newsletter #4) has a fair idea of what the customer needs so this may be a good time to consider his services. He 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.

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 - see newsletter #3)

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.

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 (including Carleton, the Doorman) and has had ample opportunity to give you their best comments. Now its up to you to determine which comments are 'keepers' and which you 'throw back'.

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. (Remember not to 'step on any toes'. Hopefully, you will have more documents to write.)

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 (unless you work with Dilbert)

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 proud family members

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

Ask for a raise (and don't say "The DocuDoctor told me to.")