Information design is an essential part of any documentation task. Here are some interesting challenges I faced at TI.

Challenge: Reducing Clutter
We put “includes” in the main Table of Contents (TOC) file to automatically import subprojects into the main TOC. But the Winhelp platform put these subprojects at the root level of the TOC (regardless of whether they deserved this kind of prominence–many were help files for minor plugins). As a result, users complained that help was cluttered and it was impossible to find things.

Solution: We migrated several of the minor subjprojects into the main help and changed the way that help files were called from within the main project. This not only improved usability, but made the project easier to manage on my end. Feedback from users was overwhelmingly positive. (See screenshot of a sample help topic with a TOC panel ).

Challenge: Mapping Documentation to a Software Methodology
TI was promoting a new method for software development, and they needed the software (and online help) to reflect this new method.

Solution: I rearranged the existing topics so that it was more hierarchical and more task-based. I also improved navigation by simplifying the left TOC panel and providing redundant links on the right main panel. Also, I implemented mid-topic links to combine shorter help topics and provided more descriptive topic labels.

Challenge: Bridge to External Information
Although the online help was good, frequently users missed many good sources of external information. That included PDF documents, knowledge bases and white papers produced for the web.

Solution: We made a second “alternate” TOC in Winhelp which actually was an html file separate from Winhelp. (See Screenshot ). This html file provided a good “bridge” to information outside of the Winhelp online help system. That included PDFs and external knowledge bases; This alternate TOC had two additional benefits. Because it was easier and less time consuming to update an html file than a winhelp project, that improved change management and made the documentation team more responsive to requests to “link to something.” Also, this file replaced another html file which was not only less functional, but was created by an html editor which used style tags instead of CSS stylesheets. By rewriting the html from scratch to use css, I eliminated about 75% of the code and made the file much easier to maintain over time.

Challenge: Embedding Help within the Application
The application team was working on an innovative advice window which offered users customized advice for their DSP program. Not only did the advice need to be easy to read, it needed to be legible regardless of the window size (Users often reduced the window size when using other aspects of the tool).

Solution: I wrote (and maintained) css stylesheets for the advice window’s html files that worked reasonably well for all window sizes. By using icons, text hidden by CSS, javascript, and hyperlinks that trigged Winhelp topics, I was able to cram lots of information into these advice windows without overwhelming users. (See a screenshot of a sample advice window and a view of the help window integrated with the application itself). I wrote this information from scratch and had to check with the application team frequently to make sure that I was conveying the tool’s behavior precisely (this information went through lots of iterations).

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.