Contextual help in the product UI

Contextual help is content sourced from our content management system and displayed in the product interface. You can work with product teams to add help popovers in the Experience Cloud or Experience Platform product UI. The help content is managed in documentation markdown files. It can include links to docs and videos.

Popover example gif

In this Experience Platform page, the following CONTEXTUALHELP element appears below the Mandatory attributes section.

syntax

The product team added the ID and JavaScript library to the Experience Platform interface page.

Dependencies

  • Requires UX guidance on popover placement
  • Requires PM and Dev agreement on placement and content
  • Requires accurate contextual links from popovers to the documentation pages
  1. Open the markdown file that you want to use as the target file for the Learn more URL.

  2. Add a CONTEXTUALHELP blurb below the target heading, as shown in this example:

    syntax

Contextual help authoring guidelines

Requirements and guidelines for authoring contextual help:

Element Requirements
id The ID that the developer adds to the product page. Work with developers to determine this value. See Developer requirements below.
The suggested ID format is: id="application_yourarea_workflow_uiitem", for example: id="platform_destinations_activate_deduplicationkey"
title The title that displays at the top of the popover. This title must match the interface element or the task or concept heading associated with the element.
abstract The definition that displays below the title. This description should be brief, one paragraph, with no more than five lines, and include UICONTROL and DNL tags where needed. Do not embed more than three links.
Begin the first line as an abstract definition, meaning, a noun phrase that is not a complete sentence. (Similar to how definitions are authored in this table.) For example, assume you are defining Real-Time Analytics Data:
>abstract="Attribute data derived from [!UICONTROL Real-Time Analytics] image requests for [creating an audience](https://experienceleague.adobe.com/docs/core-services/interface/services/audiences/t-audience-create.html?lang=en), and includes data such as eVars and events. You must select a report suite when using this attribute source, and define the dimension or event to include. This report suite selection provides the variable structure used by the report suite."
Within the description, you can link to other related help, tutorials, or courses. However, for the additional-url value, link to the product’s documentation page (described below).
additional-url The markdown file used in the Learn more link. You can create a goURL to use a goURL instead that links to a documentation or video page.

Developer requirements

Developers must add the popover JavaScript library and IDs.

Javascript library

The JavaScript library contains the JS mechanism that interprets the JSON file delivered by the DOC Jenkins Platform. The library reads the ID value contained in the web app page and renders a popover if there is a match in the JSON. The popover content is stored in the JSON file.

The Developer should add the JS library front-end for the whole app. This needs to be done only once.

Icon locations and ID coordination

The developer and documentation teams should coordinate information icon locations and IDs (described in the preceding table) to connect the UI with the documentation page.

<ContextualHelp entryId="id_value" />

Popover appearance

The popover look is defined in the library. It is compliant with spectrum/global UX recommendations. The overall look helps ensure UX homogeneity.

Additional library information

The popovers have been implemented in Campaign and Customer Journey Orchestration. This wiki page is the main entry:

https://wiki.corp.adobe.com/display/SSE/In-product+Contextual+Help+for+ExC

The JS script description and integration is documented here:

https://quarry.corp.adobe.com/documentation/@quarry/contextual-help

On this page