Static Help

Deliverables / SAP Companion

Static help provides small, focused, context-aware help in concept topics that are, where possible, associated with a hotspot on the screen.

Content Strategy

Static help can enhance the user's journey in the application by acting as that middle step between an intuitive UI and the comprehensive and technical topics found in the SAP Help Portal.

Consider user expectations and behaviors for consuming information when planning the size of help topics.

Use the questions below to determine what information is useful. Some questions may not be relevant for your project, but they should give you an idea of what your users want to know:

Minimum Requirements for BTP

information
Make sure that your SAP Companion project has this minimum set of content for your product.
<div> <div>What</div> <div>Where on Help Panel</div> <div>More info</div> <div>Prio</div> </div> <div> <div>"Link tile" to <strong>SAP Help Portal</strong></div> <div>Help tab</div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fdeliverables%2Fsap-companion-1%2Fstatic-help%2F%23tile-types-and-order">Title Types and Order</a></div> <div>Mandatory</div> </div> <div> <div>"Link tile" to any <strong>Guided Answers</strong> (if you have them)</div> <div>Help tab</div> <div></div> <div>to be decided if we keep this requirement</div> </div> <div> <div>"Link tile" to <strong>What’s New</strong></div> <div>What's New tab (dedicated tab on help panel)</div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fdeliverables%2Fsap-companion-1%2Fwhat-s-new-1%2F">What's New</a></div> <div>Mandatory on the help panel of the main entry page of your tool (no need to include What's New tab on any other pages once it's added to the main entry page).</div> </div>
information
NOTE: Guided Answers are migrating to the SAP Help Portal. You can track progress in this jira. Make sure that you update your links to point to the new location and update the link title to Troubleshooting Information.

Tile Types and Order

The static HELP PANEL can contain standalone or connected help tiles and link tiles.

Examples:

Try to limit the number of tiles to ensure that the user can see them all at once without scrolling.

We want users to see all available information at once to quickly find what they need.

information

Note that you should set up the following tabs on the static help panel:

  • Help topics tab (see below for instructions)
  • What's New tab (click here). Please follow the instructions in the Infrastructure guide.

Tile order

(1) Link tile (Open SAP Help Portal):

  • The first tile in your static help panel should be a link tile, rendered as a button, to open a page in your SAP Help Portal documentation that is relevant to the current screen context.
  • Mandatory because it ensures that a minimum viable Help topics tab is visible when your user launches SAP Companion.

(2) Standalone tiles:

  • Standalone tiles are tiles in the static help panel that are not connected to a specific UI element via a hotspot.
  • They provide general information about the entire screen.
  • Place standalone tiles below the Open SAP Help Portal link tile.
  • If you have an "About This Screen" tile (optional), it should be the first of all standalone tiles.

(3) Connected tiles:

  • Connected tiles are assigned to specific UI elements on the screen via a hotspot.
  • Place connected tiles below standalone tiles.
  • The order of the tiles should follow the order of the UI elements you've assigned hotspots to on the page (top to bottom, left to right).

(4) Video tiles:

  • Video tiles are standalone tiles that embed overview or tutorial videos relevant to the screen.
  • Place video tiles after other standalone and connected tiles.
  • Use the video icon provided by Companion, and the "Video:" keyword in the title so users can both visually scan for and filter for video content.

(5) Link tiles (additional):

  • Link tiles are rendered as buttons and link to a page outside your app or service.
  • They should be placed at the bottom of the static help panel.

Add link tiles using the titles below to link to standard resources from your Help Topics panel consistently across the BTP. A link to your SAP Help Portal documentation is mandatory.

<div> <div>Title</div> <div>Use</div> <div>Body Text</div> </div> <div> <div>Open SAP Help Portal</div> <div>Mandatory</div> <div> <p>Link to relevant documentation on the SAP Help Portal.</p> <p>Use a standard tag.</p> </div> </div> <div> <div>Tutorials or Tutorial Navigator</div> <div>Optional</div> <div>Link to filtered tutorials for your service.</div> </div> <div> <div>Troubleshooting</div> <div>Optional</div> <div>Link to Troubleshooting/FAQ topics.</div> </div> <div> <div>Troubleshooting Information</div> <div>Mandatory, if Guided Answers exist for your application.</div> <div>Link to Guided Answers information that was migrated to the SAP Help Portal.</div> </div>

Standalone Tiles

Consider adding the following types of standalone tiles to your static help panel to provide context to the overall screen, using titles consistently across BTP.

<div> <div>Title</div> <div>Use</div> <div>Description</div> <div>Body Text</div> </div> <div> <div> <p>About This Screen</p> <p>or</p> <p>About [UI Page Name]</p> </div> <div> <p>Optional</p> <p>Recommended for UI screens without a short description provided under the screen title.</p> <p>Not recommended for generalized design-time experiences where many different tasks can be accomplished on a screen (for example, SAP Analytics Cloud, SAP Datasphere, SAP HANA Cloud).</p> </div> <div> <p>General information related to this screen.</p> <p>Guidance: Use this tile if users aren't going to find the UI page intuitive.</p> </div> <div>Describe what this screen is used for and what you can do in it. Usefulness varies widely depending on the type off app or service. Avoid having redundant information that is better suited in your other help tiles.</div> </div> <div> <div>Useful Terms</div> <div>Optional</div> <div>Terms related to this screen.</div> <div>A list or table of terms that are relevant to a screen, such as statuses or destination values.</div> </div> <div> <div>Video: <Title of Video></div> <div>Optional</div> <div>Describe what the user learns from watching the video.</div> <div>Embedded overview or tutorial videos. Embed an SAP Media version of your video, with a short description of what the user will learn in the video.</div> </div>

Content Guidelines

Quick Reference: Sizing Guidance

General

This example gives supplemental information about creating a workload class

2
do
false
  • Add a title that starts with an action verb and matches the UI element or feature you reference.
  • Use people-centric language.
  • Describe the UI element in one or two paragraphs. Keep it concise!
  • Where appropriate, include links to relevant SAP Help Portal documentation. This lets the user continue the search for more information.
dont
false
  • Don't add help for self-explanatory, obvious, or generic UI elements.
  • Don't exceed two paragraphs. You can link users with an xref in the SAP Companion popover to your SAP Help Portal documentation for a deeper dive.

See also:

The People-Centric Approach (PCA) - Overview

Title

Keep these things in mind when adding a title to a tile.

The title appears in the Help topics tile and the popover. It should be the same as the short text of the data element or the label used on the UI.

2
do
false
  • For hotspot connected tiles, match the name of the UI element. See Fiori elements.
  • Use the full version for the title.
  • Use title case.
  • Restricted to 20 characters.
dont
false
  • Don't add a period after the title.

Short Description

As a best practice, keep your SAP Companion content short and concise.

Keep these things in mind when adding a short description to a tile.

The short description appears in the Help Topics tile and the popover. It introduces the topic or UI element in a single sentence.

2
do
false
  • Short Description should be visible in the static help panel.
  • Use a period if it's a full sentence.
  • Restricted to 70 characters.
dont
false
  • Don't use a period if the short description isn't a full sentence.
guideline
In your DITA CMS project map file, you can set the value of the renderer setting attribute sap.html.shortdesc.exclude to no. This ensures your short description is automatically included in both the tile preview and the popover bubble so writers don't have to duplicate the text twice.

Body Element

Keep these things in mind when creating the body text in a tile.

The body text appears in the popover only.

2
do
false
  • Use a verb at the start of the title.
  • Use links ONLY to trustworthy sources such as blogs, tutorials, or guided answers.
  • Use the xref tag for links.
  • If you link to other SAP sources, disable the disclaimer that you are leaving the SAP Help Portal. To do this, add the following rendering setting to your project map: link.sap.classification=no.
dont
false
  • Don't use a title in body text.
  • Don't use explicit UI references like ‘this field’ or ‘this indicator’ (this is important for better accessibility).
  • Don't use nested lists. Use a maximum of one sub-level for lists.

Inline Links

Sample inline link

Related links

Sample related link

To link to a page in your SAP Help Portal documentation, we recommend using a standard xref tag. This ensures that localization is handled automatically without needing a translate=yes attribute, loc-comment tag, and manual attention by the translation team.

To resolve a standard xref link at build-time:

There may be cases where your architecture is such that you must use external links. In this case, ensure that that the link text is accurate and that you check the validity of your links regularly.

To save space, please use the following format to introduce related links:

information

If your container setup in the DITA CMS prevents you from using standard xref links as above, then alternatively you could use external xref links. However, to account for different languages, you'll need to use the following workaround:

  1. In the DITA CMS, choose the tag xref in your topic and paste your URL. Add the attribute translate=yes.
  2. Add the loc-comment tag to inform translators that they must adapt the link in a way that it points to the documentation in the respective language. Also, point to the respective documentation by pasting the URL in a comment tag.

Hotspots

By assigning a hotspot, you connect a tile to a specific UI element. This ensures that the tile is only visible if the UI element appears on the screen.

The default style set by the User Assistance Steering Board for the hotspots is the green question mark icon.

guideline

Assigning and configuring hotspots is done in the edit mode of SAP Companion in your application. To open edit mode, simply enter the URL parameter ?edithelp=true to your application URL before the #. For example:

Your SAP Companion account will need edit permissions to access this. And your application may require additional URL parameters to edit an appropriate state or version. For example: &help-version=2023.22&help-stateUACP=DRAFT. If you require permissions or are unsure which parameters to add to your URL, contact the developer that is responsible for implementing and maintaining your SAP Companion project from a development-perspective.

See also:

Assigning Hotspots

Best Practices for SAP Companion Hotspots

Updating the Hotspot Style

Bubble Properties

The following properties need to be defined for each bubble:

<div> <div>Properties</div> <div>Use</div> </div> <div> <div>Bubble Type</div> <div> <p>The bubble type can be one of the following:</p> <ul> <li>None - for standalone and link tiles;</li> <li>Icon - This is the standard. Use the <strong>Help (?)</strong> icon and ensure that the size is <strong>XS</strong>. Position the icon at the top or middle end of the UI element.</li> </ul> </div> </div> <div> <div>Bubble Orientation</div> <div> <p>Use Auto</p> <p>The orientation of the bubble is relative to the hotspot.</p> <p>The available options are North (above), South (below), East (to the right), West (to the left), and Auto that automatically determines a suitable location for the bubble so that it is visible.</p> <p>Preview the result. If not suitable, then use one of the specific values.</p> </div> </div> <div> <div>Bubble Size</div> <div> <p>Use the smallest size that allows content to fit nicely, so that both the content is clearly visible, and the bubble takes up as little real estate as possible on the screen.</p> <p>The following general guidelines apply:</p> <ul> <li>For shorter texts, use XS or S.</li> <li>For lists and graphics, use M or L.</li> </ul> <p>When editing the hotspot, use the Preview button to check the result, to ensure the size is right – as small as possible for the content to fit nicely.</p> </div> </div>

UI Elements That Don't Require Help

Avoid creating help for and assigning hotspots to these UI elements:

<div> <div>Element</div> <div>Use</div> </div> <div> <div>Save, Delete, Filters, Search fields, or any obvious UI buttons</div> <div>Don’t provide embedded help for filters if they are obvious. Usually, the labels and the options are enough to understand the filters. If some filters are ambiguous or the users could use some additional explanations, then add the help following the guidelines for dropdown menus.</div> </div> <div> <div>Page Titles</div> <div>Don’t add a hotspot to a page title. If appropriate, instead create an About This Screen standalone tile in the help panel. This should describe the use of the page.</div> </div> <div> <div>Side Navigation (repeated)</div> <div> <p>Don't <strong>repeat</strong> embedded help for the side navigation on every page of your application. The page will get too cluttered and will make it hard to ensure consistency across different pages.</p> <p><strong>Tip:</strong> Explaining the apps, tools, and sections in your side navigation can be useful, and can be effectively accomplished with hotspot popovers. <strong>Do this once</strong> on a main entry page, such as the Home page of your application, so users get an explanation without repetition across all pages of your product.</p> </div> </div> <div> <div>Elements in a Table (on the UI)</div> <div>Do not create help for an element in a table on the UI, such as an entire row. You must also not assign hotspots on elements in a table.</div> </div> <div> <div>Individual Action Icons in a Table</div> <div>Do not create a topic for each action icon in a table. Instead, create a single topic called Actions and assign it to the table header. For more information, see the Table guidelines.</div> </div>

Modal dialogs appear on top of content. They can contain complex configuration or multi-step workflows that may benefit from hotspot popovers. When a modal dialog is active, the ? icon in the shell bar is inaccessible to the user. Consider working with your development team to add a ? icon to the upper-right of the dialog header where you want to include hotspot content, so that the user has a way to open the SAP Companion help.

For consistency across all dialogs, certain Data & Analytics BTP products have aligned on a single design pattern. See this UX Spec on Companion & modal dialogs.

Icon Position and Offsets

When assigning a hotspot to a UI element, there are a variety of values available for the Icon Position and Offset settings. The results you'll get can vary widely based on how your product UI is built.

It is recommended you follow any product-specific guidelines that exist. If no such guidelines exist for your product, then follow the general best practices found in the UA Infrastructure Guide, and make adjustments as needed:

Fiori Popovers

Companion hotspots are a key part of our content strategy to provide concise, summary help information, in-context, and as a bridge to the full help documentation on the Help Portal.

However, there are cases where Companion hotspots may not be suitable for your needs, and Fiori Popovers could be better suited for providing certain kinds of info in the UI.

Guidance that Trigger Actions

Sometimes you'd like to provide information as direct guidance to the user where you provide a way for the user to trigger an action in the product.

Use Fiori popovers. The bottom of the popover can be reserved for various actions such as to trigger a dialog, navigate to another part of the product, or switch modes within the existing tool.

Provide Info Without Breaking User Flow

Information message strips have the benefit of being always-visible to users in the UI. Sometimes for space considerations, message strips are not possible, and popovers are used instead.

Fiori popovers can be quickly skimmed as an information aid during a user’s execution of work. As opposed to help, when a user is confused or unsure what to do next, and needs to stop what they are doing and access help.

You'll have to make a judgement on when to provide on-screen messages that allow the user to quickly glance at additional tidbits of information as they continue with their intended workflow. Use Fiori popovers as a last resort for this type of information.

Bubble Properties

The following properties need to be defined for each bubble:

Publishing Guidelines

If you have a standalone SAP Companion product, follow the normal guidelines for publishing deliverables in UACP.

If you contribute to a large SAP Companion project, check with the project lead for guidance on contributing content for a release. For example, many UAs contribute content to the SAP BTP cockpit SAP Companion project. UAs must make sure that new content is ready according to a release schedule and one UA publishes content for the entire project.

Checklist for SAP Companion Content to troubleshoot issues that you see when preparing to publish.

See also:

Creating a Buildable Map for Static Help in the SAP Companion Help Framework

Best Practices for Creating Static Help

Creating Help Topics for the SAP Companion