Contextual Help Implementation

Contextual Help Types

Contextual helps enable you to directly access relevant content through websites or applications. The help content that you access gives you specific information about a particular application feature or even an interface element.

Contextual Help Linking to Related Content

Applications may provide related content in another window, tab, or pane.

Figure 1. Microsoft Word Contextual Help.

Clicking Help opens the Help pane where you can browse through related help articles.

Embedded Contextual Helps

Applications may provide embedded content that directs you to the relevant documentation section.

Figure 2. Amazon Contextual Help.

If you're placing an order through Amazon.com and you click the Help link from your Shopping Cart, it directs you to the relevant help content.

Contextual Help Providing Hover Text

Applications may provide information through tooltips when you hover over interface elements.

Figure 3. Hover Text on the easyDITA Website.

On the easyDITA Pricing page, if you hover over a feature, the information about that feature appears.

Conceptual Help Providing Text in Fields

Applications may provide guidance text in forms and fields.

Figure 4. Text in Fields on the easyDITA Website.

On the easyDITA Free Trial page, some fields show explanatory text.

Implement a Contextual Help

Assign unique IDs to topics or topic elements and map these IDs into applications.

Plan the contextual help implementation process with software developers and discuss the ID naming convention. See Contextual Help Implementation Guidelines.
Note: There are two general workflows enabling you to implement contextual helps into applications:
  • Assign IDs to the documentation first and then provide the IDs to software developers who map the IDs into the application.

  • Obtain the IDs mapped into the application from software engineers and then assign the IDs in the documentation.

  1. Develop new documentation or reuse the existing documentation.
  2. If software developers have already mapped IDs into the application, obtain the IDs.
  3. Depending on the contextual help type, assign IDs to topics and/or topic elements by doing one of the following:
    1. Assign IDs to topics. See Assign IDs to Topics.
    2. Assign IDs to topic elements. See Assign IDs to Topic Elements.
  4. If software developers haven't mapped IDs into the application yet, provide them with the IDs assigned in the documentation.
    Tip: We can prepare a report that makes it easier for you to share the IDs assigned in the documentation or work out another solution to automatize this process.
    Software developers then map the IDs into the application.
  5. If necessary, provide the help in the required format to software developers. See Assign IDs to Topic Elements.
    Note: By default, the DITA-OT enables you to publish helps in the following formats:
    • HTML 5

    • XHTML

    • JavaHelp

    The DITA-OT is highly customizable and can be configured to publish content that conforms to your needs. For more information, see Assign IDs to Topic Elements.

    Software developers implement the contextual help into an application build.
We recommend testing the contextual help in the application after implementation.

Contextual Help Implementation Guidelines

Contextual helps come in different forms so they may be developed and implemented in various ways.

Implementation Types

You can implement contextual help into applications in different ways, for example by:

  • Publishing a contextual help as an online asset that is linked to in an application
  • Integrating a contextual help with an application interface
  • Embedding a contextual help into a desktop application or web application
Note: Depending on your organization requirements, contextual helps may be embedded as offline assets into desktop applications. Offline contextual helps can be accessed without the Internet connection, but are more difficult to update than contextual help. To update an offline contextual help, a new desktop application version that includes the revised documentation needs to be built and deployed to target machines.

General Guidelines

Keep the following general guidelines in mind when implementing a contextual help:

  • Determine how the users access the help content in the application or on the website.

  • Assign meaningful unique IDs to the elements that you want to map into the application or website.

    For example, Section_ProjectManagement, Procedure_SavingYourProject, or ChangePasswordScreen_LoginField

  • If you want to map a topic into multiple places in an application or multiple applications, you can add several unique resource ID elements to the topic.

  • The IDs remain assigned to the topics and topic elements even if you change their contents.

Assign IDs to Topics

Assigning unique IDs is necessary to map topics into applications or websites.

Mapping a topic is useful if you plan to provide a link to a help page that gives information on a specific part of an application.
Tip: You can assign multiple unique IDs to the topic if you plan to map the topic into:
  • Multiple applications or websites
  • Multiple places in an application or on a website.
  1. Open a topic that you want to assign an ID or IDs to.
  2. In the topic editor, if you cannot see the prolog element, in the right-top corner, click the Gear icon and check the Show Prolog check box.
    Figure 5. Prolog Element
  3. Assign a unique ID to the topic by doing the following:
    1. Place your cursor in the prolog element.
    2. Insert a resource ID element.
    3. Place your cursor in the resource ID element and enter a unique ID for the topic.
    4. Optional: In the corresponding field, provide the application name in which the topic ID will be mapped.
    Figure 6. Filled in Resource ID Element
  4. If you want to map the topic in multiple places, assign more unique IDs to the topic by repeating 3.
    Figure 7. Filled in Resource ID Elements

Assign IDs to Topic Elements

Assigning unique IDs is necessary to map topic elements into applications or websites.

Mapping a topic element, for example a phrase element, into an application is useful if you want to display your content in a field or another application interface element.
Important: You can assign only one ID to a topic element.
  1. Open a topic and place your cursor in the element you want to create an unique ID for.
  2. Click the Attributes tab.
    Attributes tab screenshot.
  3. In the id field enter a unique ID.
    Tip: We recommend assigning an ID name related to the element so it's easy to identify later.
    Set the ID for a step element as stepDepressLever
    The Attributes tab with the id field filled in.