Writing Online Help (Managing & Troubleshooting a Complex Project)

End User/Intended Audience: Electrical engineers, Digital Signal Processor (DSP) developers

Tools used: Winhelp, Microsoft Office, Robohelp, Clearcase, Winmerge, Clearquest

The original online documentation for the Code Composer Studio IDE tool was delivered in the form winhelp files (generated from Microsoft Word files & Robohelp). Winhelp as an online help platform had limitations. It was buggy, didn’t scale well, was dependent on MS Word and plagued by file corruption problems. In many ways, it was a legacy documentation method, but when I started, thousands of topics had already been written using that tool, and the existing software architecture did not allow for an easy migration to a new help system like HTML help. So I needed to manage the existing architecture and project and enforce standards across documents.

Because of the potential for file and project corruption, I had to implement changes slowly and carefully and only after testing. I used Robohelp to generate the winhelp files. I started with a master project and created 10 different winhelp + TOC files for 10 different software platforms. By using “single source layouts” and conditional topics, I was able to customize documentation for each platform while maintaining a uniformity of look and feel.

Even though our company paid for the top support plan, the complexity of TI’s help project made it impractical to rely on outside experts to solve our problems. An important part of my job was troubleshooting tricky problems and devising workarounds when needed. If a F1 help call from the program didn’t work (for instance), was it a problem with the MS Word macro, the Robohelp tool, my PC or the application code that was supposed to trigger the help call? I worked closely with application developers to devise a solution when something was seriously wrong. In addition, I was responsible for fixing documentation bugs filed by other developers.

I managed the department’s documentation drops for all documentation related to software. I used Rational Clearcase version control system to provide the deliverables and created logs for easy verification about what had been dropped. Although my job title was technical writer, I actually spent about 1/3 of my time performing these system administration and troubleshooting tasks.