In a post that I published last year, I said that I would document how we implemented Ray Gallon’s double-embeddedness theory for a project we were developing. Here I am, a year later, with the details of this implementation. Better late than never, right? :)
Let’s start by summarizing Ray’s theory.
There are two main concepts in this theory:
The solution is what Ray calls “double embeddedness”:
…with progressive disclosure:
In summary, we want user assistance that:
I sat down with the developers at IXIASOFT to discuss how we could implement this theory in our new product, called Web Author. The Web Author is a web editor that allows casual contributors and reviewers to edit and review DITA topics from an Internet browser. Because users would not be familiar with DITA and would not use this tool every day, it was a perfect candidate for the type of user assistance that Ray talked about.
We started by defining three levels of help.
When users hover over an element of the UI, a pop-up is displayed with a short overview of the function. The tooltip provides some conceptual information to put users in context as they are performing the task.
The following diagram shows a sample tooltip. When a user logs in, the Web Author lists the documents that are assigned to the user. The number of documents assigned is displayed in the Number of assignments area. When users hover over this area (the purple square with a number in it), the following tooltip is displayed:
The tooltip contains a More… link so if users need more information about the area, they click the link and level 2 help is displayed.
Level 2 help provides more detailed information about the area as well as links to what you can do in this area (i.e., the actual procedures). For example, if a user clicks More in the Number of assignments tooltip, the following window is displayed:
The level 2 help is not displayed in a pop-up window, it’s embedded in the user interface, in the lower left corner of the main window, as shown above.
Another requirement of Ray’s theory is that help should be unobtrusive and be out of the way if users don’t need it. For this, we added the hide tips/show tips toggle button on top of the help details window (shown above). When users are familiar enough with the user interface and no longer want the help, they can simply disable it by clicking hide tips. Should they need to see the help again later on, they simply click the show tips button.
If a user still needs more information, clicking one of the related links will open the level 3 help.
This is a standard HTML help system available in another tab of the browser. When users click the links in the help details area, they are taken to the corresponding procedure in the online help, shown below:
To implement the user assistance, we decided to use the DITA
<resourceid> element and
To link the DITA topic to the appropriate user interface area, we use the
<resourceid> element in the
<prolog>. For example, to specify the topic that applies to the Number of assignments area, we added the following code to the topic:
<prolog> <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/> </prolog>
appname specifies the product name (in this case, the Web Author) and the
resourceid specifies the resource id of the area as specified in the Java code. This ensures that when a user hovers over an area, the Web Author knows from which topic to pull the documentation.
<resourceid> element for context-sensitive help is a pretty standard approach. What’s different about our implementation is that we decided to use the
outputclass attribute to identify what to display at each level of help.
We defined three values for outputclass:
outputclass="help_tooltip": Defines level 1 help
outputclass="help_context": Defines level 2 help
outputclass="help_related_information": Defines the related links that will open the HTML help
For example, the following code shows the DITA file for the Number of assignments topic:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE concept PUBLIC "-//IXIA//DTD IXIA DITA Composite//EN" "../../system/dtd/ixia/IxiaDitabase.dtd"> <concept id="per1389986405854" xml:lang="en-us"> <title>Number of assignments area</title> <shortdesc outputclass="help_tooltip"><ph id="number">Displays the number of documents assigned to you in the role selected.</ph> </shortdesc> <prolog> <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/> </prolog> <conbody> <section outputclass="help_context"> <p>When you select a role in the <uicontrol>Roles</uicontrol> drop-down list, all the documents assigned to you and active for that role are displayed in the Assignments pane, and the number of documents is updated in the <uicontrol>Number of assignments</uicontrol> area.</p> <p>To refresh the list and the number of active documents, click the <uicontrol>Refresh</uicontrol> icon in the <wintitle>Number of assignments</wintitle> area.</p> </section> </conbody> <related-links outputclass="help_related_information"> <link href="per1389986405575.xml#per1389986405575" outputclass="help_related_information_link"/> <link href="per1389986404838.xml#per1389986404838" outputclass="help_related_information_link"/> <link href="per1389986405139.xml#per1389986405139" outputclass="help_related_information_link"/> </related-links> </concept>
When a user hovers over the Number of assignments area, the user assistance looks for the element with the
outputclass="help_tooltip". This is usually the
<shortdesc> element. If a user clicks the More... link, the user assistance then looks for the element with the
outputclass="help_context". In the example above, the attribute is set on the
<section> element, so this whole element is included in the help details. The related links specified with the
outputclass="help_related_information" are displayed at the bottom of the help details. If a user clicks one of these links, then the user assistance opens up the complete HTML help.
This is shown in the following diagram (you might want to click the diagram to enlarge it and see the details):
One of the advantages of using the
outputclass is that it's valid on any DITA element, so it's very flexible; the user assistance only needs to look for the defined
outputclass, no matter the type of topic. We can use any element in any type of topic to produce the user assistance.
Another advantage of using the
outputclass attribute is that the same source content can be used for the user assistance, the HTML online help, as well as a PDF User Guide that was requested by our customers. But this will be the subject of another post, since this one is getting long enough already.
As you can see from this approach, a lot of magic happens behind the scenes (i.e., in the software) to enable this user assistance. I am lucky enough to work with developers who think that documentation and user assistance are very important, so they decided to treat the user assistance as a feature of the product. They developed a custom XSLT transformation scenario that generates an .hlp file with the user assistance. They also added code to the Web Author that extracts the right level of help according to user actions.
So yes, this method requires custom code from developers, but I think it's a great example of how DITA can be used to create context-sensitive help.
Again, special thanks to Ray Gallon for his research and very inspiring webinar.