The developer had rejected previous attempts to make this manual more usable. His experience had been that the editor changed the meaning of the content and rendered the documentation useless.
I analyzed the source document and noted that there were multiple products involved in the installation and maintenance of the software. The original installation instructions intertwined steps among various products. To complicate matters, there were details extraneous to the installation mixed in. For example, there were maintenance steps, descriptive information, and troubleshooting instructions. The document also omitted steps needed for the installation.
I developed a list of questions for the developer. The answers allowed me to propose a rearrangement of the content that significantly reduced the apparent complexity of the product installation, use, and maintenance.
By verifying my assumptions testing small sections of the document before the complete edit, I won the trust and support of the developer. The developer was very pleased with the outcome and supported my coming on as a full time employee.
This is the before document.
This is one round of questions and suggestions.
This is the proposed rearrangement of the content.
Major Rewrite Project
This started out as a developer-written user guide. It was really more of a tutorial. I had worked with report writer documentation in the past. I knew that report writer documentation is inherently complicated. This product was even more complicated because of the built-in security and sign-offs to meet FDA compliance.
I analyzed the original document. The document presented information for two levels of uses and an administrator. I separated the content into three documents. Each document provided information from the original document and additional information to meet the needs of each audience.
The original guide is a tutorial –
The revised guide/reference set is three user-centric documents –
This revision received a Merit Award from the STC Northern California Touchstone Technical Communication Competition.