Implement a Context-sensitive Help

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

Plan the context-sensitive help implementation process with software developers and discuss the ID naming convention. See Context-sensitive Help Implementation Guidelines.

Note: There are two general workflows enabling you to implement a context-sensitive help into an application:

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 context-sensitive 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 simplify 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 context-sensitive help into an application build.

We recommend testing the context-sensitive help in the application after implementation.

Context-sensitive Help Implementation Guidelines

Context-sensitive help comes in different forms so they may be developed and implemented in various ways.

Implementation Types

You can implement context-sensitive help into applications in different ways, for example by:

Publishing it as an online asset that is linked to in an application
Integrating it with an application interface
Embedding it into a desktop application or web application

Note: Some products require context-sensitive help to be embedded as an offline asset into a desktop application. An offline context-sensitive help can be accessed without the Internet connection, but is more difficult to update than a context-sensitive help that requires access to the Internet. To update an offline context-sensitive 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 context-sensitive 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 button 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 for which you want to create an unique ID.
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 short description element as sample_id

Gretyl's Portal

Heretto Help