DocumentationExperience League Authoring Guide

Contextual help in the product UI

Last update: Fri Sep 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Contextual help is content sourced from our content management system (SCCM) and displayed in the product interface. You can work with product teams to add help popovers in the Experience Cloud or Experience Platform product UIs.

Popover help content is managed in documentation Markdown files and can include links to docs and videos.

Example of a popover example

Here’s an example help popover with instructions on how to it is configured.

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 and requirements for in-product help requirements

Product documentation (from PM/Eng) is considered to be part of the product that Adobe sells. Writers and internal contributors must adhere to the following requirements for authoring and placing in-product help:

  • UX guidance on popover placement and icons
  • PM and Engineering agreement on placement and content technical accuracy
  • Editorial guidance for consistency in style and presentation
  • Accurate contextual links from popovers to the documentation pages

Contextual Help for EXC documentation and wikis wikis

Add a help popover in Markdown popup

Follow these steps to author popover help in Markdown:

  1. Open the markdown file that you want to use as the target file for the Learn more URL.

  2. Add an explicit anchor to the heading of the section where the contextualhelp blurb will be included.

    Example: ### Mandatory attributes {#mandatory-attributes}

    An explicit anchor is required so that it will remain the same for all languages.

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

    syntax

Contextual help authoring guidelines 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 popover 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.)

Editorial examples

Real-Time Analytics Data:

Attribute data derived from Real-Time Analytics image requests for creating an audience, 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.

Organization ID:

The entity that enables an administrator to configure groups and users, and to control single sign-on in the Experience Cloud. The organization functions like a log-in company that spans all the Experience Cloud products and applications. Most often, an organization is your company name. However, a company can have many organizations as described in Organizations in Experience Cloud.

Within a 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 developer

Developers must add the popover JavaScript library and IDs.

JavaScript library js-lib

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.

   import { ContextualHelp } from '@quarry-connected/exl-help';
   ...
   <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-connected/exl-help

recommendation-more-help
92f1a422-8a81-400b-85d3-388f0c36dfda