RSS 
Email 
Twitter
FacebookDiscovering Relationship Tables
August 3rd, 2009 | Posted in Technical Writing 10 Comments »
Lately I’ve been creating context-sensitive help for an online application. As part of my strategy, I’ve been trying to follow Theresa Putkey’s advice in “Usability in Context-Sensitive Help.” In her article, Theresa recommends providing more than just the steps for a specific task in the context-sensitive help window. Instead, she says to show more contextual links, including answers to why, when, and who questions, because too frequently the user who searches for help may have needs outside the specific task you describe.
Theresa explains,
The traditional way of providing content in a context-sensitive help link has been to link to the procedure for the page. Not only can this be limiting for the user, but it also can be limiting for the writer and the company. By picking a specific procedure, the writer is guessing at what the user wants to do on the page. While usability testing would give us more insight, if we don’t have this option, we can make the context sensitive help link more applicable to more people by providing a link to both a How topic and the Why, When, and Who information.
If we don’t provide additional options in the context-sensitive help, we are, in effect, making it more difficult for users to have their questions answered. By forcing them to browse and search through a help system they may be unfamiliar with, and by not highlighting the various options available for that screen, window, or page, we limit the options for the user and perhaps contribute to higher support costs.
To provide a variety of links to the user, you can manually list them, which is tedious and prone to error. Or you can use something like Related Links or Concept Links, which shows a list of links in a hard-to-see pop-up. However, there’s also another option: relationship tables. I’m new to this concept, but my initial experience with them has gotten me excited.
Relationship tables come from the world of DITA, but Madcap now gives you the ability to create them in Flare 5. From one table you can manage all the related links for your entire project. Although you can define exclusions and inclusions, basically links in the same row are part of a family, and that family can appear on each topic that you embed the relationship table on.
For example, in the following table, I have four columns.
| Concept | Task | Reference | |
| Plugins | About Plugins | Installing Plugins
Editing Plugins Removing Plugins |
Lists of Recommended Plugins |
| Themes | About Themes
Theme Hierarchy Columns in Themes |
Installing Themes
Modifying Theme Stylesheets Customizing Theme Categories |
Best Magazine Themes |
After inserting a relationship table proxy into your Flare masterpage, and setting each link type as a “Family” link type, here’s what automatically shows up on each page.
On all the plugins pages, you’ll see the following:
Related Concepts
- About Plugins
Related Tasks
- Installing Plugins
- Editing Plugins
- Removing Plugins
Reference Reference
- Lists of Recommended Plugins
Note: If you’re viewing the Installing Plugins page, the Installing Plugins doesn’t appear in the list of links. (The same smart exclusion isn’t true of Flare’s Concept links.)
On the themes pages, the list of related links would look like this:
Related Concepts
- About Themes
- Theme Hierarchy
- Columns in Themes
Related Tasks
- Installing Themes
- Modifying Theme Stylesheets
- Customizing Theme Categories
Reference Topics
- Best Magazine Themes
The cool thing is that you can manage all your related links from this one table. You can also specify more details with relationship tables, such as having links only appear on certain pages and targets, and applying conditional tags. But the basic concept is simple.
I’ve even styled my relationship table links so that they float in a narrow side column to the right of the main topic. My approach for context-sensitive help is to list the most common task for the page in the main column, and then provide the list of related links in a sidebar on the right. If the user clicks the help and says, no, that’s not what I want, he or she won’t need to scroll down to the end to see related topics.
For more information on relationship tables in Flare, see About Relationship Tables in Flare’s help.
Tags: context-sensitive help, DITA, related links, relationship tables, Theresa Putkey, usability
What I like best about relationship tables is that they allow you to craft a context-sensitive user experience that is completely independent of the TOC experience. I use the relationship table to establish only links that are directly relevant to the task at hand, and I let the TOC provide the broader spectrum of topics that could also interest the user. For example, a TOC might group all tasks that relate to Reports, such as designing templates, scheduling reports, searching for acrchived reports, printing reports, etc. But the relationship table, for example, might link the task topic on Printing a Report to just a few relevant topics, such as configuring a printer. It helps keep users focused on the task at hand.
Mike, I was thinking about what you said yesterday — that relationship tables allow you to craft a context-sensitive experience different from the navigation in the TOC. You’re so right. I initially just made my relationship tables based on the folder structure in my TOC. Later, I realized that the questions users may have on one page in the app span multiple folders in the TOC, so the relationship tables really do provide an opportunity for an alternative organization of links — one based on pages rather than by topic. Thanks for the tip.
Relationship tables are a great way to connect topics. In fact, one of the best things of using this relationship method is that you can relate different topics to a single topic when you use that topic in a different context so that the relationships are practically dynamic from one information set to the other.
It was interesting to see Flare take the concept from their DITA work and apply it to other information source.
Julio, I’m interested to learn more about how Flare’s use of relationship tables differs from the standard tables in DITA. If you want to elaborate, feel free.
Hi Tom,
When I had time to beta test Flare, I don’t even think relationship tables were implemented yet. I’m not sure that there is much difference but as Flare supports more output formats than the DITA OT, there has to be unique implementations for each unique type. I have to believe that Flare has to do things to process relationship tables that are different from the OT but not necessarily better or worse. If I gave the impression that the differences were significant, that’s my bad.
BTW, I would have never thought to have had a 4th column in a reltable as a hint to the writer, so I applaud that use case. I would have used it as a task to task relationship column (with possible alteration of the linking attributes to prevent incorrect linkages to the concept and reference topics). I’ve always looked at reltables as a method to express relationships among topics that don’t have a navigational relationship.
What I’m most interested in is the day when Flare has full authoring support for DITA, which is still to come.
It’s also worth mentioning that relationship tables (at least in DITA) save you the grief of discovering all the broken links that that appear when you go into a topic reuse frenzy…
Relationship tables are a part of the map that references the topics in your deliverable. If the topic is not in the map, it cannot go into the relationship table, and thereby cannot create a broken link.
Soren — thanks for pointing that out. Good to know. I appreciate your participation in the comments.
I have just opened the link with more information on relationship tables in Flare and I can say that it is a treasury
[...] relationship tables. I just discovered relationship tables a few weeks ago, but it greatly simplifies related links by allowing me to manage all my links in [...]
[...] Discovering Relationship Tables [...]