Cisco · Metadata-Driven Help

Making Help Match the Device in the User’s Hand

Generic help could point users toward features their phone did not support or their administrator had chosen not to allow. The help system automatically assembled the right content on the fly, required no separate help configuration, and changed when the phone’s enabled features changed.

The Problem

Help on Cisco IP Phones created two customer problems when it described features that were not available to the person using the phone. Users could follow links to features that did not exist on their phones, leaving them confused about what the phone was supposed to do. When a feature was available but an administrator had chosen not to allow it, visible help could also create pressure to enable something the organization did not want users to have.

The mismatch created confusion for users, more support work for administrators, and avoidable costs for customers. Because feature availability varied by phone and configuration, one generic help package could not accurately describe every user's phone.

The help was embedded in the phone firmware. It needed to feel like part of the product rather than a separate manual that happened to be available from the interface.

Why It Was Hard

The phone model alone did not determine which help a user needed. Administrators could turn features on or off in the software that managed the IP Phone system, so people using the same model at the same company could have different feature sets. Power users, including executive assistants, often needed advanced capabilities that regular users did not.

A static help package for each model would therefore still have been wrong for some users. The architecture had to preserve common explanations while changing topics, feature lists, related links, and navigation according to both the device and the features an administrator had enabled. The source needed to remain reusable while the finished help stayed specific to the phone and its enabled features.

What I Figured Out

Feature availability was metadata, not a reason to copy the documentation.

Once the help system could identify the phone and its enabled features, it could select the applicable content from shared source automatically and on the fly.

What I Changed

I designed the help around that distinction. Feature metadata drove the topics, related links, lists, and navigation appropriate to the phone and its administered configuration, while shared explanations remained in shared source. The help was assembled automatically from the phone’s current feature set. Administrators did not have to configure the help separately. They managed the phone features in the existing system, and the help followed that configuration.

The work included the content as well as the mechanism. I wrote the help content that would be deployed in the firmware, built and evaluated prototypes, and conducted usability testing to determine whether people could find and use the help.

What Changed as a Result

Users received help that matched the phone and configuration in front of them. When the enabled features changed, the help changed with them. Users were not sent looking for nonexistent features, and administrators were not left explaining or defending features the organization had chosen not to enable. Writers could correct or improve shared content once without exposing every model to features it did not have.

The resulting content was deployed on millions of phones. Writers maintained shared explanations once, while users saw help specific to the phone and features in front of them.

Evidence and Technical Detail

Structured FrameMaker, feature metadata, reusable source, variables, conditional content, generated topics and links, firmware-embedded help, prototypes, product testing, log analysis, and usability testing supported the device- and feature-specific help.