Contextual Help Implementation
Contextual Help Types
Contextual Help Linking to Related Content
Applications may provide related content in another window, tab, or pane.
Embedded Contextual Helps
Applications may provide embedded content that directs you to the relevant documentation section.
Contextual Help Providing Hover Text
Applications may provide information through tooltips when you hover over interface elements.
Conceptual Help Providing Text in Fields
Applications may provide guidance text in forms and fields.
Implement a Contextual Help
Assign unique IDs to topics or topic elements and map these IDs 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:
- 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 Assign IDs to Topic Elements.Note: By default, the DITA-OT enables you to publish helps in the following formats:
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.
Contextual Help Implementation Guidelines
Contextual helps come in different forms so they may be developed and implemented in various ways.
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
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.
- 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.
- Assign a unique ID to the topic by doing the following:
- Place your cursor in the prolog element.
- Insert a resource ID element.
- Place your cursor in the resource ID element and enter a unique ID for the topic.
- 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.
- 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