Documentation Embedded Interactive Diagrams

For B2B Advanced Communications

What if we added interactive diagrams to supplement our traditional documentation?

Roles:

Technical Writing / Documentation Design

During my first year at IBM, I wrote documentation for an enterprise product called B2B Advanced Communications. The documentation was all text describing how to integrate and install highly complex enterprise software. Sometimes diagrams were provided, but they were often diagrams taken from internal slide decks. They were complicated, unattractive, and most of all, confusing. They seemed to serve a very small audience of those with internal knowledge or very specific topology building experience.

What if we could offer something visually striking and intuitive? To design a better diagram, I would need to do some research and interview our stakeholders, just as I did when writing documentation. With our developers and software architect, I went back and forth with multiple drafts and notes until we had something that was both intuitive and an accurate depiction of the architecture. For the diagrams to be consistent with the offering branding, I would also need to create a visual language. Collaborating with a visual designer working on a similar parallel project, we put together a rudimentary visual language that shared some consistency across our products.

Once completed, I wondered if we could add some sort of interaction to add to improve the troubleshooting experience. I used basic HTML image mapping and reformatted it into DITA to make the diagram interactive. Each component in the diagram was linked to the root page of its corresponding DITA article. For example, if a user was unfamiliar with the back-end system, they could click that part of the image to learn more about that component. We already used the same concept to move between articles, so this would remain a familiar paradigm.

I received some positive responses from internal stakeholders, but there was no way to determine how the diagrams affected the experience of our actual customers. We still were working on integrating web analytics into the documentation database, and at the time I didn’t have access to users to conduct interviews. With the design and research experience I’ve gained since then, it would be interesting to find out if this concept would truly improve the support and troubleshooting experience for our users.

While no longer live on the help database, you can view the finished diagrams on the right.