As a technical writer developing large online help projects, I faced challenges in managing the editing process–specifically, ensuring consistency across each of the help files and controlling versions of the help as edits are made. In this article, I describe the editing structure and process adopted in our department to help address these problems, which, as a result, has minimized errors in the online help. This editing cycle works well for us, and other documentation departments could benefit from adopting such a process for large online help projects.
Background
Hansen Information Technologies provides enterprise-wide, asset-based data management software to a large international client base consisting of state and local governments. The software is composed of dozens of modules designed for specific areas of government management, including billing, building permits, code enforcement, customer service, land management, and licensing. Each module contains several forms that manage related information. For example, the Asset Valuation module includes forms for valuing assets, generating revaluations, and generating depreciations.
Using RoboHelp, Word, and Paint, our department produces online help and training workbooks to support this complex software. The online help is particularly complex, involving more than three hundred help files and thousands of supporting documents:
System help provides introductory material, step-by-step instructions, and case studies for each of the modules.
- Form help provides form-specific information, such as field and button descriptions, hot-spotted images for quick reference, and step-by-step instructions. The form help is accessible from the system help and from the forms themselves via a help button.
We produce our content in Word, edit it, and then fold it into the online help using RoboHelp.
Pinpointing Problems with Managing Online Help Edits
We faced two major problems with managing an editing cycle for an online help project of this size and complexity:
- Consistency across help files With the number of help files being produced, consistency across each help file was critical. It was easy to overlook or forget simple formatting issues such as when to use bold text, when to use bulleted lists, what order to put box or button descriptions in, and so on. These were issues that a template could not resolve because they depended on context and did not apply to every section of the document. New writers and editors who were not familiar with the existing styles also complicated formatting issues because they learned the styles as they worked and made mistakes during the learning process.
- Version control Producing more than three hundred help files required hundreds of supporting documents that were folded into those files. New or updated material could easily be overwritten with older material at any point during editing. The number of documents produced increased the likelihood that a document might miss an edit if steps weren’t taken in advance to organize the entire cycle.
Because of these problems, we concluded that a thorough editing cycle would be critical–one that includes a precise set of guidelines to ensure consistency and a strict file structure to maintain version control. As such, we developed a structure for an editing cycle and implemented a three-phase process.
Establishing Structure to Support Edits
In beginning to address the problems, the department developed a comprehensive Writer’s Desktop Reference (WDR) to ensure style consistency. The WDR contains detailed style guidelines, project development guidelines, research tips, troubleshooting for RoboHelp, and more. It’s compiled into a help file using the same format used for the online help that the department creates. In the event that information needs to be presented in a format that is not covered in the WDR, the writer and editor can bring up the issue at one of the biweekly department meetings. Once a change is made, the writers are notified, and the WDR is updated.
We also developed a fairly simple file structure to maintain version control. The department established separate folders for form help and system help. The attached illustration (formfile.gif) shows the Form Help folder structure.
The Form Help folder contains a folder for every module. Within each module folder is an Images, In Progress, and Reference Guide folder. The In Progress folder contains documents that are in the process of being written. The Reference Guide folder contains all of the folders needed for the editing cycle for the form help.
The second folder the department established was the System Help folder, shown in the attached file sysfile.gif.
The System Help folder contains a folder for every module, using the same naming conventions found in the Form Help folder. Each module folder contains all of the folders needed for the editing cycle.
Implementing an Editing Process
In addition to developing the WDR and a file structure to support online help edits, we also implemented a more structured editing process. Writers produce documents in Word according to WDR styles, and use the file structure described previously to store work-in-progress documents. Once a document is completed, writers place it into the editing cycle. Because each form and module folder contains a set of folders that match the editing cycle (see previous graphics), the writers and editors can move documents from one folder to the next as each stage of the editing cycle is completed. The department uses Word’s Track Changes feature for all edits, eliminating paper waste. The following sections outline the stages of the editing cycle:
- Technical Edit
- Content Edit
- QA/QC (Quality Assurance/Quality Control)
Technical edits. Once writers complete a document, they place it in the Tech Edit Needed folder and then notify the SMEs (Subject Matter Experts) that it is ready for the tech edit. The 
SMEs are drawn from project leads, programmers, and trainers, depending on their availability and the complexity of the module.
The department furnishes each SME with a short document (attached, techguide.pdf) that describes the purpose of technical edits and provides tips on what to look for. Basically, the SMEs check to make sure that all functionality is covered and accurately described, and that needed processes are included. The SMEs work from their own computers and deliver edits via email or drop boxes.
Once writers receive a document that has been through the tech edit, they place it in the Tech Edit Revision Needed folder and delete its original (non-edited) copy from the Tech Edit Needed folder. The writers then make the necessary changes and move the document into the Content Edit Needed folder.
Content edits. Editors, then, move the document from the Content Edit Needed folder to their computer and begin editing. Editors perform content edits to check for grammar and spelling, and to ensure that the style and format conform to the WDR. They also check for content, meaning, and clarity.
Once the editors complete these edits, they move the document into the Content Edit Revision Needed folder. Writers, then, make any necessary changes and move the document to the Ready For RoboHelp folder, if it’s part of form help, or the Ready folder, if it’s part of system help.
QA/QC As writers complete content edit revisions for each document, they prepare it for RoboHelp and fold it into a help file following a procedure set out in the WDR. Once the help file is completed, the document goes through a departmental QA/QC process, which is usually a peer edit.
QA/QC has two stages:
- In QA/QC 1, someone in the department (usually another writer) checks the completed help file for format and function errors, such as broken links, title bar heading, and TOC (Table of Contents) functionality. If time permits, the person also proofreads the help file. If the person performing the edit finds mistakes, she notes these errors on a QA/QC checklist. Once she completes QA/QC, she delivers the checklist back to a writer. The writer then corrects any errors and informs the next person responsible for editing the project that it is ready for QA/QC 2.
- In QA/QC 2, a different person checks the help file to make sure all corrections have been made and to double-check for any serious problems that may have been missed in previous edits. The person copies the help file to her own computer and fixes any problems found. When this QA/QC edit is completed, the person deletes the original help file and pastes in the edited one.
The help file is completed after QA/QC 2. It’s then given to product development for inclusion in the next software release. All work-in-progress copies of the help files are deleted, and the completed project is stored in read-only format on the server using Visual Source Safe. It’s also backed up to CD.
Conclusion
Our documentation department uses a thorough editing cycle that minimizes problems in a fast-paced work environment. The comprehensive WDR provides writers and editors with detailed guidelines for formatting and stylistic issues, which reduces consistency problems across all help files despite the number of help files we produce. The file structure provides a path along which completed documents travel through the editing cycle. Files that have not been edited remain safely in the appropriate Edit Needed folder. This structure reduces version control problems and helps to reduce problems such as file overwrite or missed edits. Because of the simplicity of the file structure and the benefits gained from its use, this editing structure and process could be helpful in other documentation departments that work with large online help projects.
Sean Hower lives and works in Sacramento, California. You can reach Sean at hokumhome@freehomepage.com.
Attachments
Guidelines for Technical Edits
