Open topic with navigation

About Context-Sensitive Help

This feature is supported in DotNet Help, HTML Help, WebHelp, WebHelp Plus, and WebHelp Mobile output.

Context-sensitive Help (CSH) is a way to "tie" your existing topics with specific dialogs or windows in a software application, or with simple Web links created somewhere (e.g., on a website). When users open a particular dialog or window in a software application, or click a Web link, they can quickly open a topic pertaining to it.

example

Let's say you are creating an online Help system for your company's software application. This application contains a dialog called "Properties" that users open to specify settings for a particular element. In your Help project, you have written a topic to explain this Properties dialog. By creating CSH, users will be able to open that specific topic by clicking a Help button on the Properties dialog (or by pressing F1 when it is open).

Who is involved?

Creating CSH is mostly a joint effort between you and the software developer. There are tasks that you must perform and tasks that the developer must perform in order for CSH to be implemented successfully. For this reason, it is essential that you communicate clearly with the developer when planning, creating, and implementing CSH. Other individuals (managers, other Help authors, etc.) may also be involved as well, particularly in the early planning stages.

However, there might be times when you function as both the author and the developer. For example, this might be the case if you are generating WebHelp output and simply want to create links on a website that open specific parts of your output. In that situation, you might first generate the online output with the CSH information. Then you might serve as the developer, modifying pages on a website to include CSH links pointing to your documentation.

Planning the CSH

For CSH to be successful, some initial planning is necessary. This includes making decisions such as:

• Which type of output is being created (e.g., DotNet Help, WebHelp, WebHelp Mobile)?
• Which dialogs and windows will be included in the CSH (if connecting to an application)?
• Where will the links be located (if connecting to simple Web links)?
• What will the Help buttons look like on the dialogs or windows?
• Will the CSH Help topics open in a different window than the other topics in the Help system (different size, position, and appearance)?

Depending on how your company operates, questions such as these may be decided independently by you or the developer. Or they may be decided jointly by you, the software developer, and others (managers, other authors).

Another major decision that needs to be made at the beginning of the process is whether you or the developer will be responsible for providing the header file that is necessary for CSH. This decision is typically made jointly by you and the software developer. See About Header Files.

What needs to be done and who does what?

Following are two sets of general guidelines containing the necessary steps for creating CSH. Each set of guidelines is slightly different, based on whether you or the software developer provides the header file.

CSH Steps — If You Provide the Header File

1. You — Add a header file to the project.

   See About Header Files and Adding Header Files.

   Note: If you are importing FrameMaker documents and you create topic alias markers in the source files, this file will be created automatically when you perform the import. See Creating Topic Alias Markers in FrameMaker for Context-Sensitive Help.

2. You — Add an alias file to the project.

   See About Alias Files and Adding Alias Files.

   Note: If you are importing FrameMaker documents and you create topic alias markers in the source files, this file will be created automatically when you perform the import. See Creating Topic Alias Markers in FrameMaker for Context-Sensitive Help.

3. You — Create and assign identifiers.

   See Creating and Assigning Identifiers.

   Note: If you are importing FrameMaker documents, you can create topic alias markers in the source files as an alternative to creating identifiers in Flare. When you import the FrameMaker files, the identifiers will be created for you in Flare. See Creating Topic Alias Markers in FrameMaker for Context-Sensitive Help.

4. You — Associate the alias file with the target.

   This is necessary only if you have created more than one alias file. See Associating an Alias File with a Target.

5. You — Provide the developer with a copy of the header file.

   For example, you can do this by exporting the file to a shared drive. See Providing a Developer with a Header File.

6. You — Generate output.

   See Building Output.

7. You — Provide the developer with a copy of the Help output files.

   See Distributing Output.

8. Software developer — "Hooks" application interface or Web links to online topics.

   The developer connects the dialogs, windows, or Web links to the appropriate online topics using the information in the header file. See the following for more details about the information that you might need to provide for the developer (depending on the output type you generated).

   • CSH Calls for DotNet Help
   • CSH Calls for HTML Help
   • CSH Calls for WebHelp and WebHelp Plus
   • CSH Calls for WebHelp Mobile
9. Software developer — Creates a new build of the software application or publishes updated Web links.

10. You — Install the new software build or view updated website. Test the CSH.

    See Testing Context-Sensitive Help.

CSH Steps — If Developer Provides the Header File

1. Software developer — Creates the header file.
2. Software developer — Provides you with a copy of the header file.

3. You — Add the developer's header file to the project.

   See About Header Files and Importing Header Files.

4. You — Add an alias file to the project.

   See About Alias Files and Adding Alias Files.

5. You — Assign identifiers for the header file.

   See Creating and Assigning Identifiers.

6. You — Associate the alias file with the target.

   This is necessary only if you have created more than one alias file. See Associating an Alias File with a Target.

7. You — Generate output.

   See Building Output.

8. You — Provide the developer with a copy of the Help output files.

   See Distributing Output.

9. Software developer — "Hooks" application interface or Web links to online topics.

   The developer connects the dialogs, windows, or Web links to the appropriate online topics using the information in the header file. See the following for more details about the information that you might need to provide for the developer (depending on the output type you generated).

   • CSH Calls for DotNet Help
   • CSH Calls for HTML Help
   • CSH Calls for WebHelp and WebHelp Plus
   • CSH Calls for WebHelp Mobile
10. Software developer — Creates a new build of the software application or publishes updated Web links.

11. You — Install the new software build or view updated Web links. Test the CSH.

    See Testing Context-Sensitive Help.

See Also

Open topic with navigation