We have limited UA capacity in some areas, which leads to UA teams struggling to fully support the most strategic products and services while still providing legally sound UA deliverables for those with lower priority. In addition, we need to meet legal requirements and comply with SAP product standards, as well as ensure consistent user experience and service adoption across the portfolio.
To achieve this, we have introduced a UA concept for SAP Business Technology Platform (BTP) that defines the required set of UA assets and respective processes to cover the legally required content and basic information on how to use the service. This approach allows UA to shift resources to strategically important services and products.
This concept:
Establishes a fair prioritization and reliable collaboration model between UA and development teams.
Provides consistency for SAP BTP users and an improved user experience for the most important services.
Allows us to free up UA capacity and focus on strategically important services and products.
Note: This concept applies to SAP BTP services with development investment up to 200 FTE. All other cases, such as larger SAP BTP services with 200+ FTEs consisting of multiple components, will be handled case by case by UA/UX managers. In such cases, the concept can be applied to selected components only. A service in the context of SAP BTP is defined in the SAP BTP documentation on the SAP Help Portal.
Basic concepts
Essential UA scope The definition of the required set of UA assets and respective processes in case of budget constraints or insufficient UA resources. The essential UA scope covers the legally required content and basic information on how to use the service. In the context of minimal UA support, the responsibility for this content is split between UA and product/development teams.
Minimal UA support The subset of essential UA assets, created and maintained by UA. The list of minimal UA support assets depends on the use case.
Additional information (other assets) The content that can be provided to extend the information about the service and support its adoption and usage. In the context of minimal UA support, the responsibility for this content lies with the product/development teams.
Use cases
Depending on the available UA assets for the service, we distinguish between two use cases:
Use case 1: New service, no UA deliverables exist A service is considered new if there is no externally published information for that service.
Use case 2: Existing service, UA deliverables exist A service that is visible in the Discovery Center and for which externally published information is available.
Note: Once the essential scope supported by UA is published for a service, it is considered an existing service (use case 2).
How to determine if a service qualifies for essential UA scope coverage
If one of the following criteria applies, the service is a candidate for essential scope coverage. The final decision is made by the respective UA/UX manager. The assessment can be revisited after a certain period of time depending on the planning cycle of the service.
No UA planned/available in the project team or no budget planned for UA support by the project team
For existing services: low service adoption (based on metrics analysis, interpretation may differ depending on service type) Metrics : Service users, purchased licenses, service usage, documentation usage, Discovery Center access, conclusions from help needs analysis
Low strategic importance: - no roadmap items planned - no active development for the service or the service is in maintenance - the service has a low rank in the SAP BTP strategy - deprecated or redundant (existing in another service) functionality
Guidelines: New Service
A new service, in the context of essential scope, is a service for which there is no externally published information available yet.
Note: Once the essential scope supported by UA is published for a service, it is considered an existing service (use case 2).
UA provides an initial set of UA deliverables. Once these assets are published for a service, it is considered an existing service and the commitments for use case 2 apply. Content is delivered in English only.
For assets provided by development/product teams, UA provides guidelines about how to create those assets. The responsibility to create those assets based on the guidelines lies with the product team/development organization.
<div> <div>Asset</div> <div>Provided by</div> <div>Details</div> </div> <div> <div><strong>Terminology (key terms)</strong></div> <div>UA</div> <div> <p>The basis for all deliverables; needed for consistency. UA provides service names (long/short), service plan, the key concepts/terms for the service.</p> <p>Provide proper and consistent terminology is a product standard <strong>UA-50</strong> as described at <a href="https%3A%2F%2Fhelp.sap.com%2Fdocs%2FSNG_FOR_UA%2Fe33c591ae4494a659a3f5f983c9d1161%2F7ea0335681d94c81a2f5d1a31518906e.html%3F%26state%3DDRAFT">Terminology and SAPterm.</a></p> </div> </div> <div> <div><strong>What’s New</strong></div> <div>UA</div> <div>Mandatory according to the Product Standard for UA and required for revenue recognition.</div> </div> <div> <div><strong>Feature Scope Description (FSD)</strong></div> <div>UA</div> <div>Mandatory according to the Product Standard for UA. Describes the high-level features of the service. More information: <a href="https%3A%2F%2Fworkzone.one.int.sap%2Fsite%23workzone-home%26%2Fgroups%2F6gwKfMkkoUDCmbM1C90DsU%2Fdocuments%2FbtOlNFKDtBGCHI85XcctCP%2Fslide_viewer%3F_lightbox%3Dtrue%26label%3DSlide%25201">FSD Best Practices</a>.</div> </div> <div> <div><strong>Data Sheet</strong></div> <div>UA</div> <div>Required to display the service in the Service Catalog of the SAP Discovery Center; the content is reused in BTP Cockpit, the service guide, and the FSD. More information: <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fproduct-specifics%2Fsap-btp-services%2Fservice-data-sheet%2F%23reuse-of-data-sheet-topic-content">Reuse of Data Sheets</a>.</div> </div> <div> <div><strong>Service Guide (core sections)</strong></div> <div>UA</div> <div>For essential UA support, we use a simplified service guide template with a reduced scope. The following sections (if relevant) should be covered: what's new, initial setup, accessibility, security. More information: <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fua-strategy%2Fcontent-planning%2Fessential-ua-scope-and-minimal-ua-support%2F%23simplified-service-guide">Simplified Service Guide</a>.</div> </div> <div> <div><strong>Product Pages</strong></div> <div>UA</div> <div>The entry point to all UA deliverables on the SAP Help Portal; incudes links to the FSD, What's New, Service guide, and other content (created by the development/product team, such as tutorials, guided answers, and so on).</div> </div> <div> <div><strong>In-App Help (review only)</strong></div> <div>UA</div> <div>The draft UI texts, tooltips, short descriptions and error/log messages are provided by the development team. UA developers review and edit the content.</div> </div> <div> <div><strong>In-App Help and SAP Companion</strong></div> <div>Dev/product team</div> <div> <p>Development provides draft UI texts, tooltips, and error/log messages in compliance with the defined terminology and the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fui-texts%2Foverview%2Fbtp-ui-text%2F">Guidelines for UI Texts</a>. UA developers review and edit the texts.</p> <p>SAP Companion (formerly Web Assistant) content is not supported as it requires access to DITA CCMS. To be considered if an escalation is triggered.</p> </div> </div> <div> <div><strong>API Documentation</strong></div> <div>Dev/product team</div> <div> <p>Provided by development in the (<a href="https%3A%2F%2Fwiki.one.int.sap%2Fwiki%2Fpages%2Fviewpage.action%3FspaceKey%3DNDW%26title%3DWriting%2Band%2BPublishing%2BAPIs%2Bto%2BSAP%2BAPI%2BBusiness%2BHub">API Guidelines</a>).</p> <p>*We recommend a review by UA prior to validation. If no review has happened and there are UA-related issues during the validation, the product team needs to allocate UA resources and request a UA review.</p> </div> </div> <div> <div><strong>Reference Information</strong></div> <div>Dev/product team</div> <div>CLI commands/help provided by development in the CLI.</div> </div> <div> <div><strong>Troubleshooting</strong></div> <div>Dev/product team</div> <div>Optional content, created in the Guided Answers tool. Can be provided by development and/or Product Support (<a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fdeliverables%2Fsupport-portal%2Ftroubleshooting%2F">Troubleshooting</a>).</div> </div> <div> <div><strong>Tutorials, Blogs</strong></div> <div>Dev/product team</div> <div> <p>Tutorials are created in the Tutorial Navigator and contain how-to content.</p> <p>Blogs in the SAP Community can contain conceptual information.</p> <p>Both can be provided by development, PM, and/or other groups (<a href="https%3A%2F%2Fworkzone.one.int.sap%2Fsite%23workzone-home%26%2Fgroups%2FA7NmsKmoG9vVaxizKhdQOk%2Foverview_page%2Fr9dX7mvdcXW5KMmWvG2NYl%3Frc%3D1">How to create tutorials</a>).</p> </div> </div> <div> <div><strong>Service Guide (extended)</strong></div> <div>Dev/product team</div> <div> <p>No UA support for extended content, such as administration, development, integration, or end-user guides. Possible options for development are to provide:</p> <ul> <li>Concepts in blogs</li> <li>How-to information in tutorials/missions</li> </ul> </div> </div> <div> <div><strong>Discovery Center Missions</strong></div> <div>Dev/product team</div> <div>We recommend a UA review of the texts, if possible.</div> </div> <div> <div><strong>Others</strong></div> <div>Dev/product team</div> <div> <p>No UA support will be provided for additional learning or UA assets, such as Learning Journeys.</p> <p>For more information about creating learning material on <a href="https%3A%2F%2Flearning.sap.com%2F">learning.sap.com</a>, see the <a href="https%3A%2F%2Fsap.sharepoint.com%2Fsites%2F200657">SAP Learning Guidelines</a>.</p> </div> </div>
Guidelines: Existing Service
Use case 2: existing service
An existing service in the context of essential scope is a service that is visible in the Discovery Center and there is externally published information about it.
Note: Once the essential scope supported by UA is published for a service, it is considered an existing service.
Assumption: There is existing content and previous UA involvement; minimal UA support is to be offered to maintain the existing information in the DITA CCMS.
<div> <div>Asset</div> <div>Provided by</div> <div>Details</div> </div> <div> <div><strong>Data Sheet</strong></div> <div>UA (minimal maintenance)</div> <div>Required to display the service in the Service Catalog of the SAP Discovery Center; the content is reused in the BTP cockpit, service guide, and the FSD (<a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fproduct-specifics%2Fsap-btp-services%2Fservice-data-sheet%2F%23reuse-of-data-sheet-topic-content">Reuse of Data Sheets)</a>.</div> </div> <div> <div><strong>Feature Scope Description (FSD)</strong></div> <div>UA (minimal maintenance)</div> <div> <p>Mandatory according to the Product Standard for UA.</p> <p>Describes the high-level features of the service. More information: <a href="https%3A%2F%2Fjam4.sapjam.com%2Fgroups%2F6gwKfMkkoUDCmbM1C90DsU%2Fdocuments%2FbtOlNFKDtBGCHI85XcctCP%2Fslide_viewer%3F_lightbox%3Dtrue%26label%3DSlide%2B1">FSD Best Practices</a>.</p> </div> </div> <div> <div><strong>What’s New</strong></div> <div>UA (minimal maintenance)</div> <div>Mandatory according to Product Standard for UA and required for revenue recognition.</div> </div> <div> <div><strong>Product Page</strong></div> <div>UA (minimal maintenance)</div> <div>Entry point to the UA deliverables; includes links to the available assets.</div> </div> <div> <div><strong>API Documentation</strong></div> <div>Dev/product team</div> <div> <p>Maintained by development in the SAP API Business Hub (<a href="https%3A%2F%2Fwiki.wdf.sap.corp%2Fwiki%2Fdisplay%2FNDW%2FWriting%2Band%2BPublishing%2BAPIs%2Bto%2BSAP%2BAPI%2BBusiness%2BHub">API Guidelines</a>).</p> <p>*For new APIs, we recommend a review by UA prior to validation.</p> <p>If no review has happened and there are UA-related issues during the validation, the product team needs to allocate UA resources and request a UA review.</p> </div> </div> <div> <div><strong>In-App Help and SAP Companion</strong></div> <div>Dev/product team</div> <div> <p>UI texts, tooltips, error/log messages maintained by development in compliance with the defined terminology and the <a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fui-texts%2Foverview%2Fbtp-ui-text%2F">Guidelines for UI Texts</a>.</p> <p>SAP Companion (formerly Web Assistant) content is not supported as it requires access to DITA CCMS.</p> <p>Possible options:</p> <ul> <li>If the entire content is outdated, the development team disables it.</li> <li>If content for individual screens/guided tours is outdated, UA removes any productive deliverables from UACP.</li> <li>To be considered by UA if an escalation is triggered.</li> </ul> </div> </div> <div> <div><strong>Help Portal Content</strong></div> <div>Dev/product team</div> <div> <p>No maintenance. To be considered if an escalation is triggered.</p> <p>If an external GitHub repository is already configured, management and ownership to be handed over to development.</p> </div> </div> <div> <div><strong>Troubleshooting</strong></div> <div>Dev/product team</div> <div>Maintained by development and/or product support (<a href="https%3A%2F%2Fwiki.wdf.sap.corp%2Fwiki%2Fdisplay%2FNDW%2FGuided%2BAnswers">Guided Answers Wiki</a>).</div> </div> <div> <div><strong>Tutorials, Blogs</strong></div> <div>Dev/product team</div> <div> <p>Tutorials are created in the Tutorial Navigator and contain how-to content.</p> <p>Blogs in the SAP Community can contain conceptual information. Both can be provided/maintained by development, PM and/or other groups (<a href="https%3A%2F%2Fjam4.sapjam.com%2Fgroups%2FA7NmsKmoG9vVaxizKhdQOk%2Foverview_page%2Fr9dX7mvdcXW5KMmWvG2NYl%3Frc%3D1">How to create tutorials</a>).</p> </div> </div> <div> <div><strong>Reference Information</strong></div> <div>Dev/product team</div> <div>CLI commands/help maintained by development in the CLI.</div> </div> <div> <div><strong>Discovery Center Missions</strong></div> <div>Dev/product team</div> <div>We recommend a UA review of the texts, if possible.</div> </div> <div> <div><strong>Others</strong></div> <div>Dev/product team</div> <div> <p>No UA support will be provided for additional learning or UA assets, such as Learning Journeys.</p> <p>For more information about creating learning material on <a href="https%3A%2F%2Flearning.sap.com%2F">learning.sap.com</a>, see the <a href="https%3A%2F%2Fsap.sharepoint.com%2Fsites%2F200657">SAP Learning Guidelines</a>.</p> </div> </div>
Simplified Service Guide
For the essential UA support, we use a service guide with a reduced scope and a simplified template. The following sections (if relevant) should be covered:
<div> <div>Section</div> <div>Description</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fproduct-specifics%2Fservice-guide-template%2Fwhat-is-service-name%2F">What Is [Service Name]?</a></div> <div>Gives an overview of the goals, advantages, and features of a service.</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fproduct-specifics%2Fservice-guide-template%2Fwhat-s-new-for-service-name%2F">What's New for [Service Name]</a></div> <div>Describes what is new as of a certain date.</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fproduct-specifics%2Fservice-guide-template%2Finitial-setup%2F">Initial Setup</a></div> <div>Summarizes the tasks that need to be performed when setting up the service in a subaccount and enabling it to be consumed by a target application.</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fproduct-specifics%2Fservice-guide-template%2Fsecurity%2F">Security</a></div> <div>Alerts the account administrator or application administrator to settings and configurations that are relevant to operating their service in a secure manner.</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fdesign-system%2Fbtp%2Fwriting-guidelines%2Fproduct-specifics%2Fservice-guide-template%2Faccessibility-features%2F">Accessibility Features</a></div> <div>Summarizes the accessibility features that are available for your service. It should let users with special needs know if they can use the service without problems or if they need to do any configuration beforehand.</div> </div>
Escalation Process
This section describes the process in case of customer escalation for missing or incorrect documentation for which no UA is assigned.
An escalation can be triggered by:
a customer ticket
an internal customer escalation
The process differs slightly depending on whether an internal GitHub repository in GitHub Tools
exists for the service documentation.
No internal GitHub repository exists
The support engineer/internal dispatcher assigns the ticket to the dev/product team (forwards the request if no ticket exists).
The dev/product team uses the commenting functionality on the SAP Help Portal to provide detailed information about the changes needed.
The PO/dev contacts the respective UA/UX manager.
The respective UA/UX manager evaluates and decides on further action.
Internal GitHub repository exists
The GitHub repository administrator creates an escalation label . See Managing Labels.
The support engineer/internal dispatcher assigns the ticket to the dev/product team (forwards the request if no ticket exists).
The developer creates a pull request with detailed information about the required changes and assigns the escalation label.
The repository dispatcher contacts the respective UA/UX manager.
The respective manager evaluates and decides on further actions.
Example
The example is based on the existing Gamification service documentation.
In this example, we assume that Gamification is a new service and show what the documentation would look like if we apply the essential scope concept.
The simplified service guide is created and maintained by UA in the DITA CCMS. The other content could be created and maintained by dev outside of the DITA CCMS.
