Information Design and Architecture

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).