15.6. RFRS Considerations

The "Help" section of the RFRS Requirements includes nine itemsone requirement and eight best practicesdealing with help.

15.6.1. Provide help through help system (RFRS 3.7.2)

Requirement #1 states:

Help for the Extension's Eclipse user interface should be provided through the Eclipse help system integrated to it. This includes the interface (menu items, toolbar entries, etc.) used to launch externally integrated vendor tools. Help for portions of your tool that are not tightly integrated to Eclipse may be provided through any existing help system it may use.

To pass this requirement, open the plug-in manifest for your help plug-in and point out the use of the org.eclipse.help.toc extension point. For the Favorites view, point to the following lines from the plugin.xml file.

<extension point="org.eclipse.help.toc">
   <toc file="toc.xml" primary="true"/>
   <toc file="tocgettingstarted.xml"/>
   <toc file="tocreference.xml"/>
</extension>

Next, open up the Eclipse Help window and show that your plug-in's help book appears in the main topic list. For the Favorites view, you would show that Favorites Guide appears in the list (see Figure 15-13 on page 552).

If your plug-in includes online help that is not provided through the Eclipse help system, show it here.

15.6.2. Provide all help via the help system (RFRS 5.3.7.1)

Best Practice #2 states:

Provide all help for your plug-in through the Eclipse help system integrated to the Eclipse UI.

As with Requirement #1, open the plug-in manifest for your help plug-in and point out the use of the org.eclipse.help.toc extension point. Open the Eclipse Help window and show that your help book is available. This best practice is actually a refinement of Requirement #1, where the only difference is that, to pass this test, your plug-in should provide all its online help through the Eclipse help system.

15.6.3. Context help activated using F1 (RFRS 5.3.7.2)

Best Practice #3 states:

Context help, if available, should be activated through F1. For products that are tightly integrated, this requires that help be associated with one or more of the SWT or JFace widgets used to construct the user interface.

To pass this test, provide scenarios where pressing F1 will show context-sensitive infopops for your plug-in. For the Favorites view, you would show the infopop associated with that view (see Figure 15-18 on page 559).

15.6.4. Implement active help (RFRS 5.3.7.3)

Best Practice #4 states:

Implement active helps for topics that are best illustrated by using workbench actions. For example, consider a topic called "Importing external plug-ins." Instead of telling the user to go to the workbench and select File > Import, and then select External Plug-ins and Fragments and click Next, the topic could simply say "Click here to open the Import External Fragments wizard." The link would call a class you have defined, which in turn would open the wizard on that page.

Passing this test is much more difficult as it requires implementing one or more active help elements. Show how your active help elements call back into your plug-in to launch various wizards or other commands. For more information on creating active help, see the "Active Help" topic in the Platform Plug-in Developer Guide included in the online Eclipse documentation.

15.6.5. Use of stand-alone help (RFRS 5.3.7.4)

Best Practice #5 states:

If help is not tightly integrated to the Eclipse UI, then use stand-alone help or a Web server-based information center.

This test is basically the reverse of Best Practice #2, so only one or the other can be passed (good thing they are not both listed as requirements). For this test, demonstrate any non-workbench-based help provided with your application. For the Favorites view, the Web page access button added earlier might qualify.

15.6.6. Use of additional documentation (RFRS 5.3.7.5)

Best Practice #6 states:

If additional documentation is provided (beyond readme files), it should be included in one of the plug-in directories used to implement the product or provide integrated help. This might be in a \doc subdirectory or a plug-in directory with a name such as co.tool.doc.

Last-minute additions to the documentation or other product guidance that did not make it into the integrated documentation should be included in a readme file in the plug-in directory.

To pass this test, show any additional documentation provided with your plug-in such as readme files or evaluation guides.

15.6.7. Provide an overview of tasks flow (RFRS 5.3.5.34)

Best Practice #7 states:

Give an overview of the tasks' flow. One or two sentences describing what is "produced/generated/created" when the user completes all the steps in the cheat sheet; in addition to this, information about sample scenarios or code can be added here. Break the information into separate paragraphs.

To pass this test, access one of the cheat sheets defined for your plug-in and show that it includes an introductory paragraph providing an overview of the tasks' flow.

15.6.8. Illustrate only one task (RFRS 5.3.5.35)

Best Practice #8 states:

Each step in a cheat sheet must only illustrate one task and involve using only one tool (wizard, dialog or editor etc.).

a. If a task using more than one tool, you should implement one step per tool.

b. If the step requires user to perform the action without launching any tool, it is a manual step. Item description must instruct the user to press the appropriate button after the task has been completed.

To pass this test, access one of the cheat sheets defined for your plug-in and show that each step illustrates only one task and involves only one tool.

15.6.9. Provide help link with each step (RFRS 5.3.5.36)

Best Practice #9 states:

Each step must have a help link with information specific to the task described in the step. The help link shows additional information to help user understand the task, complete that step, or get more advanced options relating to the task. More help links can be placed in the launched page.

To pass this test, access one of the cheat sheets defined for your plug-in and show that it includes a help link with information specific to each step.