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.

MS word help example — 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.

Amazon contextual help example — 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.

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.

Develop new documentation or reuse the existing documentation.
If software developers have already mapped IDs into the application, obtain the IDs.
Depending on the contextual help type, assign IDs to topics and 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.
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.
If necessary, provide the help in the required format to software developers.

The DITA-OT is highly customizable and can be configured to publish content that conforms to your needs.

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.

Open a topic that you want to assign an ID or IDs to.
In the Content Editor, if you cannot see the prolog element, in the right-top corner, click the Gear icon and check the Show Prolog check box.
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.
If you want to map the topic in multiple places, assign more unique IDs to the topic by repeating 3.

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.

Open a topic and place your cursor in the element you want to create an unique ID for.
Click the Attributes tab.
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

Gretyl's Portal

Heretto Help