Maintaining Milestones & Schedule For Technical Documentation

This newsletter focuses on the importance of maintaining the documentation milestones and schedules for developers of hardware and software systems or products. Lets first briefly discuss a few basic principles for establishing documentation milestones with respect to the system’s development.

Every good documentation manager knows the value and importance of developing the documents concurrently with the system being developed. The very first step in initiating the documentation tasks is to establish what documents are needed and what information they will contain. The creation of each document’s outline is the most important step in organizing the documents. As a rule of thumb, outlines should be started about the same time the system design is near completion. Once the document outlines are drafted for all the required documents, it becomes readily apparent which sections in each document can be completed during the system’s development cycle and where the milestones for each section’s completion should be established.

The remainder of the document’s development should be divided into as many sub-tasks as practical with each corresponding to a milestone for the developing system. As an example, the completion of the user screens by the developers should be followed by the inclusion of the screen images into the user’s manual, design document, and any other document including that content. For a typical engineering development project, the information reflected in the documentation should be no more than a few weeks behind the system’s progress. As each major milestone of the system’s development is reached, the documentation reflecting the system at that milestone should be archived for later reference. Reasons for this, as well as other reasons for developing documents concurrently, are discussed in the next paragraphs.

1) Keeping documents current and version controlled helps chart the evolution of the system’s design. Engineers and developers can refer to documents of previous versions to re-visit past designs or methods that can help them “fine-tune” their current design. ADVANTAGE: This can help eliminate repeating past errors and minimize trouble-shooting and debugging.

2) Documents that are well-written and carefully maintained throughout the project’s development lifecycle give the appearance of a highly organized, efficient, and disciplined development team. ADVANTAGE: Any customer would feel reassured that he had chosen the right contractor should he be handed a comprehensive document describing his system while making an unexpected visit.

3) It is much easier and less costly to start writing the documents while still early in the system’s development and maintain them throughout the entire development cycle. The task of documenting a system is always more pleasant to the technical writers, engineers, and managers when each task is kept to a manageable size. ADVANTAGE: This avoids confusion and frustration, expensive budget overruns, and corner-cutting at the end of the effort, particularly when faced with rapidly approaching delivery deadlines.

4) Documents that evolve with the system provide more opportunities for review by engineering, management, and customer personnel. When a customer is able to review the documents, such as the user’s manual or design specification, he is better able to visualize the system and make changes that may better fit their needs. Also, when a customer is asked to review the developing documents, he feels more involved regarding the system’s development. He/she achieves a greater understanding and appreciation of the difficulties experienced by the engineering team. ADVANTAGE: This can sometimes result in an expanded scope of work for the developer or contractor.

5) Documents describing the current and past systems can be used to train new members joining the development team. When new members come aboard, they can be brought “up-to-speed” by
reading documents that cover the system’s design evolution. ADVANTAGE: The time required by technical managers to “educate” new employees can be greatly reduced.

6) Documents form a record of what has been done to date. When documents are well-maintained, they contain the knowledge and information that the design engineers possessed at that point in time. ADVANTAGE: Should the engineer leave the team, there is less concern that the valuable design information is stored only in the “gray matter” of the departing member. This can also eliminate the necessity to bring former team members back as
high-priced consultants.

7) For systems that are developed in phases or builds, current version-controlled documents serve as a record of the system for that phase’s design and implementation. Multi-phase systems are sometimes delivered to the customer incrementally with each phase being operationally utilized by the end-user. In this case, complete documentation should always accompany the delivery. ADVANTAGE: The customer can immediately begin enjoying
all the wonderful benefits of the system as described in the manuals.

Additionally, a new customer may only desire the capabilities provided by a previous phase and may wish to purchase the system in the phase that best suits their needs. Well-maintained documentation will allow a completed phase of the system to be sold as a stand-alone item.

8) Testing of the system during all phases can be more readily accomplished when the system has been consistently documented. Frequently, the testing activities conducted, either for formal or in-house testing, are derived from the system’s user manual, installation document, or maintenance handbook. These documents should always contain the latest procedures for using the system. ADVANTAGE: The creation of test procedures is simply a matter of copying the steps and adapting them to the appropriate test scenarios.

9) Documents that are developed concurrently with the system can be organized such that information flows efficiently between them. Many of the system’s technical documents can contain redundant data or similar topics with varying levels of detail that may all be impacted by a single modification to the system. ADVANTAGE: The technical writer has a much easier task updating all of the affected documents if they are developed concurrently with each other and the system.

10) Documents that are developed with the system are completed at very nearly the same time the system is ready for delivery. Delivery of a product or deployment of a system should never be delayed because the documents are not completed. When this occurs, the developer can be unnecessarily exposed to missed sales, imposed penalties, or a damaged reputation. ADVANTAGE: A customer will be more likely to sing the praises of a developer or vendor that delivers his product AND his full suite of documentation when-promised.

11) On rare (and always unpleasant) occasions, funding for a system’s development may be halted or withdrawn. Frequently, the customer will then request that the system be delivered in its current condition along with all accompanying documentation. Should this happen, the project manager should have up-to-the-minute documentation to hand over to the customer. ADVANTAGE: The developer provides his customer with documentation that can help him salvage as much as possible from the terminated effort. Also, the developer can bill the customer for the time spent developing the partially completed documentation.

The documentation manager’s role in establishing milestones and deadlines should always produce a finished product within a reasonable time following completion of development and testing of the system. Of course, the technical writing tasks must follow whatever project management templates are being implemented.