Project: Create Help for Web-Based Survey Analysis Software
The Challenge: The internet survey analysis application was highly customizable. The challenge with the documentation was that each client should only see the documentation for the features they had access to. Localization was not an immediate concern, but the process had to be ready for localization. Video demonstrations of the key functionality were included. A late addition to the requirements meant that access to the videos also had to be controlled by the client definition.
The Solution: We chose to create DITA XML source files and used the DITA Toolkit plus custom post-processing scripts to generate html web help. The scripts generated project files based on a client definition XML file that defined what features each client had access to. The scripts also generated custom Tables of Contents and Indexes for each client which accessed a standard set of files. Specific sets of documentation were tied to the internet survey application login.
Only one set of source files is maintained. The generation process is largely automated and flexible enough to accomodate client specific content for clients who want business specific user instructions. The initial project generated 331 flavours of the documentation set. DITA XML is setup for localization.
Project: Create High-level Operator's Guides for a Holodeck
The Challenge: In a very short time create operator's guides for a remote, sophisticated visual environment that includes an auditorium and a cave (a room where stereo 3D projections can be displayed on all four walls and the ceiling and floor). Tracking allows users to interact with the media: a holodeck! The challenge was to create documentation without having seen the environment or most of the equipment.
The Solution: Research for the documentation included interviews with the designers, purchasers, and programmers; reviews and walkthroughs of design and engineering drawings; and experimentation with the test software. The resulting manuals were developed in MS Word and delivered in PDF format. Each manual includes a reference section for the wireless control panels, required information about integrated subsystems, and a number of setup and use walkthroughs that demonstrate the interaction of the controls and subsystems.
Note: I did get a chance much later to see the staging of another cave. Having put on the tracked 3D glasses, it was cool to walk into a test scenario and walk through a tunnel, peek "around" a corner, and bend down to look at a vehicle's under-carriage.
Project: Increase Manufacturing Speed
The Challenge: Increase manufacturing speed by reducing the amount of reference reading technicians have to do during the manufacture of a specialized computer systems.
The Solution: The resulting instructions are in a set of linked Power Point presentations. The process instructions rely heavily on photographs, screen captures and diagrams. Where required, tables and easily scanned lists back the graphics. It is possible to perform most of the procedures without focusing on the text.
A simple example of the approach: Hard Drive Conversion.
Project: Modernize Manuals to Match Product Redesign
The Challenge: System-based, reference-heavy organization of the existing manual did not clearly outline what the users needed to do to successfully use the product.
The Solution: The redesigned guide had to be easy-to-use for relatively low-tech users. A function based approach identified the major roles that would use the different aspects of the software and outlined steps required to get a multiple-display wall up and running. Reference material was separated out of the procedures and linked where appropriate.
Project: Contract Tracking Module
The Challenge: Design the user interface for a Contracts module and supervise and assist with the documentation for the new module in an enterprise asset management software system. The Contracts module was phase II of a larger project on which I had been lead writer.
The Solution: Phase two involved doing several jobs at once:
- Designing a module according to specification laid out in phase I
- Supporting the development team
- Supervising the documentation development and assisting.
The client was very pleased with the resulting module and the project came in on time and under budget.
Project: Backdoor Transaction Processing
The Challenge: An existing technical manual for backdoor processing of failed pharmacy benefits transactions was causing non-technical business consultants and their clients headaches. The manual was incorrect in both its overall assumptions of how the mechanism was supposed to work, and in its procedures. No GUI exists for the mechanism. The developers were no longer with the company.
The Solution:
- Determined the intended purpose of the software widget by interviewing business consultants and management.
- Worked with a development manager to figure out how the mechanism worked.
- Determined the level of ability of the business consultants.
- Developed conceptual information to help consultants understand the information structure, and process flow.
- Developed detailed instructions for reprocessing failed transactions.
Project: Rebuild a writing team.
The Challenge: A writing team the interviewers described as troubled and unfocused. The company was about to start a large contract and needed to sort out the issues fast.
The Solution: Within six month, the writing group was on track and ramping up to the new project. Within the first year:
- Assessed the writers' abilities and will, and developed a plan to get the group on track. Grew the team to nine writers.
- Overhauled the writing process.
- Developed a process for rapid cross-training of all the writers on product/tools knowledge.
- Developed and implemented writing career training (e.g., work estimation and progress assessment, technical documentation techniques and trends, leadership, and team building skills).
- Integrated the writing group into the overall software development process and raised awareness within the company of the growing knowledge base in the writing group. Developed support for writers among development managers and staff.
- Selected, trained and successfully put forward my replacement.
