easyDITA Documentation

send feedback

❮ Previous Next ❯

Contextual Help Implementation Guide

Learn about contextual help types and plan your 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.

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/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.
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. See Publish Maps or Topics.
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 Publish.
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 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 1. Prolog Element

prolog elementtitle element
Assign a unique ID to the topic by doing the following:
1. Place your cursor in the prolog element.prolog element
2. Insert a resource ID element.resource ID elementprolog element
3. Place your cursor in the resource ID element and enter a unique ID for the topic.resource ID element
4. Optional: In the corresponding field, provide the application name in which the topic ID will be mapped.resource ID element
Figure 2. Filled in Resource ID Element
If you want to map the topic in multiple places, assign more unique IDs to the topic by repeating 3.

Figure 3. 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.

easyDITA MindTouch Connectorresource ID elementMindTouchMindTouch

Open a topic and place your cursor in the element you want to create an unique ID for.
Click the Attributes tab.

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

Publish a Resource

You can publish your topics or maps to various formats.

In the content library, hover over a resource, click the Output icon, and click Publish. Publish window
From the list on the left, select a publishing scenario.

Figure 1. Publish Window
Optional: In the Enter Description field, enter a meaningful description.
Once you publish the document, this description appears in the list of finished publishing jobs.
Set the publishing scenario options.
The publishing parameters are specific to each publishing scenario and are configured by your easyDITA administrator. The publishing scenarios can include the following parameters.

transtype

Defines output format, like PDF or HTML.

args.filter or ditaval

Enables you to select a DITAVAL file for conditional publishing.

args.rellinks

Specifies linking settings in the output.

args.draft

Specifies if the draft comment elements are included in the output.

Locales

Enables you to select a locale when publishing localized content.

Webhooks

Enables you to send webhooks on successful publish or any publish.

Debug publish

Generates additional files in the debug folder that you can use to troubleshoot your publication.
Click Publish.
The map or topic publishes. It may take a moment to complete.

Figure 2. Output Tab
Download the published files by hovering over the publishing job and clicking the Download icon.
Optional: See the publishing job details by clicking its name.

Figure 3. Publishing Job Details

Publish window

There was a problem loading this topic