Company Name: Texas Instruments, Houston, TX
Job: Technical Writer
Dates: August 2002-February 2006

LinkedIn Testimonial: Project Manager Dana Smith

Introduction: Digital signal processors (DSPs) are the little chips in cellphones, wifi card, HDTVs and digital cameras that convert analog signal to digital signals (and vice versa). Texas Instruments is the #1 seller of DSPs worldwide, and one reason customers prefer a TI solution is that TI’s software development kit includes a number of powerful software tools.

During the years I worked at Texas Instruments, the most important development tool was a mature full-featured GUI software tool named Code Composer Studio Integrated Development Environment (which was included in every development kit). Code Composer Studio IDE was a Windows-based tool with a major release generally every two years and minor releases every six months. In fact, new features were being added continuously to Code Composer Studio and often introduced for individual hardware platforms. Writing documentation for CCS was a team-effort; although I probably “owned the project” more than anyone in my group, other writers in our group provided key components to it.

My task/challenge was to manage this chaos! I managed the main project, which consisted of about a dozen smaller subprojects. When I started at TI, the help project (if you combined everything) already consisted of several thousand help topics. I had to maintain the documentation and add new help topics when needed.

See also: more detail about my TI work projects and writing samples from TI and other companies.

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.

End User/Intended Audience: new customers & existing customers wishing to upgrade.

During my work at TI, I produced two “What’s New” guides. These were 8-10 page documents that were released on the website whenever there was a major release.

• Code Composer Studio IDE Getting Started, v. 3.1 (PDF)
  
• Code Composer Studio IDE Getting Started, v. 3.2 (PDF)
  

These two documents provide a user-friendly view of the new features in the new software product. The aim was to make a persuasive case for upgrading.

To obtain the information for these documents, I used existing online help which I created (along with other team members) during the early phases of product development. Later, I worked with the product’s marketing team to figure out which features to emphasize and how they would benefits to the user. I drafted the original document but amended it several times during the draft phase to incorporate suggestions from reviewers.

Tools used: Initially, we used an in-house Unix-based content management system to generate PDFs. Later, my company started migrating all their documentary repositories to be XML-based, so for the second one I used the XMetal XML editor to produce structured XML content (using an in-house DTD) which later was transformed by the Astoria XML document repository into PDF content.