What Is [Service Name]?

Product Specifics / Service Guide Template

<div> <div></div> <div></div> </div> <div> <div><strong>Target group</strong></div> <div>Purchaser, application developer, account administrator, application administrator</div> </div> <div> <div><strong>Mandatory / Optional</strong></div> <div>Mandatory</div> </div> <div> <div><strong>Size</strong></div> <div>Always one single topic</div> </div> <div> <div><strong>Template LOIO</strong></div> <div> <p>loio5d73f4cb8c104e6bb8c5ca90cf9e9d0d</p> <p>(use topic from <strong>version DEV</strong>, not from version 2.0)</p> </div> </div>

Revision History (Major Changes Only)

<div> <div>Change</div> <div>Date</div> </div> <div> <div>Added section Multitenancy Support.</div> <div>Q1 2023</div> </div> <div> <div>Updated the info about the <shortdescr> tag of the topic (should consist of intro sentence + the service short description re-used from the data sheet)</div> <div>Q4 2022</div> </div> <div> <div>Added a placeholder for the Beta disclaimer note (before the service short description).</div> <div>Q4 2021</div> </div> <div> <div> <p>Why information added.</p> <p>The topic overview is updated (the questions answered by the topic are changed).</p> </div> <div>Q4 2021</div> </div> <div> <div>Section Environment moved after Features.</div> <div>Q4 2021</div> </div> <div> <div>In section Environment: The standard formulations are changed ("runs in" is replaced by "available in")</div> <div>Q3 2021</div> </div> <div> <div>New section added: Technical Constraints</div> <div>Q1 2021</div> </div>

Authoring Process

A template for the service overview topic is provided in the DITA CMS: loio5d73f4cb8c104e6bb8c5ca90cf9e9d0d

As a UA developer, use Copy with new LOIO in the context menu to create your own overview topic in your product-specific container.

At four places in this template, you will find a placeholder called LOIO_DATASHEET_TOPIC. This is a placeholder that must be replaced by the loio of your service-specific data sheet topic to make the four conkeyrefs work.

guideline

As a prerequisite, you must have created a data sheet topic for your service. The texts for title, short description, description, and features within this service overview topic will be reused from that data sheet topic.
For more information on how to create a data sheet topic, see Data Sheet Topic

More information on the authoring process of both the data sheet topic and the service overview topic, including a system demo, can be found in the meeting minutes and in the recording of the SAP Cloud Platform User Assistance Meeting on September 26, 2018: SAP Cloud Platform User Assistance Meeting#MeetingMinutes26.09.2018

The Topic

Title: What Is <UA Short Name>?

Use "What Is <UA Short Name>?" as title of your topic. Do not replace it with another title. Use title case.

If you have a variable representing the UA short name for your service, use it here. If you don't have one, we strongly encourage you to create such and use it. See SAP BTP: Service Names and Variables Explained.

DITA Short Description (<shortdesc> tag)

Introduce the service long name + the SAP BTP abbreviation using one of the following standard formulations (depending on your service name):

Learn more about the SAP Business Technology Platform (SAP BTP) <short name> service. For example: Learn more about the SAP Business Technology Platform (SAP BTP) Connectivity service.

Learn more about <UA short name> service for/on SAP Business Technology Platform (SAP BTP). For example: Learn more about SAP Application Logging service for SAP Business Technology Platform (SAP BTP). Learn more about OAuth 2.0 service on SAP Business Technology Platform (SAP BTP).

If you have a variable representing the service name, use it here. If you don't have one, we strongly encourage you to create such, and use it.

Service Short Description (from the data sheet)

Replace the placeholder LOIO_DATASHEET_TOPIC in the conkeyref with the loio of your data sheet topic.

As a result, the DITA short description (<shortdescr>) element of the topic should consist of the intro sentence above + the service short description re-used from the data sheet. Note that the service short description should be in imperative form (see the guidelines for service names and descriptions).

Example:

Let's take OAuth 2.0 service. This is how the DITA source code for the short description should look like:

<shortdesc>                     Learn more about OAuth 2.0 service on SAP Business Technology Platform (SAP BTP). <ph conkeyref="loio03783afba9854a5b91c4ff7ffb3bba56/ct_shortDescription"/>                      </shortdesc>

which should result in the following output:

Learn more about OAuth 2.0 service on SAP Business Technology Platform (SAP BTP). Protect applications and APIs with OAuth 2.0.

Service Long Description (from the data sheet)

Replace the placeholder LOIO_DATASHEET_TOPIC in the conkeyref with the loio of your data sheet topic.

Why Information

Immediately after the service long description, provide the WHY information. Don't use a section title. it should appear as continuation of the service description.

Provide here short information helping the customer understand why they should use this service. Focus on one key aspect, not the whole list of features, use cases, advantages or supported scenarios.

Customer questions that should be answered by this section:

Is the service relevant to me?
Why should I prefer this service over other similar products on the market?
Why should I invest into a product like that at all?

You could approach this information in several different ways depending on your service specifics and the preferences of the service PO/PM.

Choose only one of those approaches:

This topic gives an overview of your service.

It answers basic questions like, "What is the service? What does it do? Why use this service? (What are its benefits?) (Does it match my use cases?)"

<div> <div>Approach</div> <div>Description</div> <div>Hints</div> </div> <div> <div>Main technical advantage/benefit</div> <div> <p>What is the technical aspect that makes your service better than its competitors?</p> <p>Use it only for features that are important and meaningful to the customer.</p> </div> <div> <ul> <li>Your service supports a huge number of database objects (probably more than competitors),</li> <li>a large number of concurrent sessions (more than the average),</li> <li>all protocol flows in a communication protocol, etc.</li> </ul> </div> </div> <div> <div>Key differentiator</div> <div> <p>What feature makes this service stand out of all other products with similar features?</p> <p>Do not repeat here the complete list of features. Focus on the one most important aspect.</p> </div> <div> <p>SAP product enablement:</p> <ul> <li>Your service enables (seamless) integration with other cloud or on-premise SAP products.</li> <li>Your service comes pre-configured for use with SAP identity services or an SAP on-premise system.</li> <li>etc.</li> </ul> </div> </div> <div> <div>Prominent use case/scenario</div> <div> <p>Can you identify a best use case that illustrates clearly the benefits of using your service?</p> <p>Do not repeat the complete list of use cases. Focus on your best example here.</p> </div> <div>A typical or most beneficial customer scenario.</div> </div>

guideline

If you want to create detailed descriptions of your service benefits, use cases or key differentiator, create dedicated topics in your service guide, or write a blog. Provide a link to them from this section.

WHY Information Guidelines

Keep it short and sweet. Make sure your point is clear and well-stated. Avoid technical details.
Do not repeat or contradict other sections, especially the long description, the Features and Use Cases sections. Make sure they complement each other's information, and make consistent text flow.
Stick to the facts. Vague statements only dilute your point and have no place in technical documentation.
Do not promise anything (such as increasing revenue, impenetrable security or systems that will run error-free).
Avoid any kind of marketing language, generalization or overstatement (“best-in-class”, "one-of-a-kind", "unique capabilities", "top-notch security", etc.)
If you refer to non-SAP products in your description, use the appropriate product trademarks.
Link to missions and roadmaps in SAP Discovery Center. However, refrain from adding a vast collection of links. Restrict them to 3.

Tips:

We strongly recommend involving a PO/PM or support contact into this. We recommend having an open discussion rather than an e-mail conversation.

Involve a language editor to create really crisp and meaningful texts.

Features

This section is mandatory.

Replace the placeholder LOIO_DATASHEET_TOPIC in the conkeyref with the loio of your data sheet topic.

Environment

This section is mandatory.

In this section, explain in which environment your service is available/consumable. Use one of the standard formulations below.

If your service is available only in one environment:

This service is available in the Cloud Foundry/Neo/Kyma environment.

If your service is available in several environment:

This service is available in the following environments:

Neo environment
Cloud Foundry environment
Kyma environment
Other (specify in which)

Multitenancy Support

This section is mandatory if your service supports multitenancy.

Use the following standard formulation:

This service supports multitenancy. It can be used in tenant-aware applications.

Overview Graphics

This section is optional.
You can choose a title for this section that matches your graphic, for example, "Architectural Overview" if your graphic gives an architectural overview of your service. Please make sure your graphic complies with the guidelines for graphics: Graphics.

Use Cases

This section is optional.
Describe possible business processes and scenarios for your service. If there are other services related to your service, mention them here. This could be, for example, if the service has several APIs but not all of them are used at a given time but they all have their specific use cases. If your service is a development tool, describe in which context it is used.

Prerequisites

This section is optional.
Describe what you need to do before you can use the service productively. This can include additional software, services, hardware, and licenses.

Tools

This section is optional.
List all tools that can are part of your service.

Technical Constraints

This section is optional.

Use it to document:

Technical constraints such as sizes, quota, max and min number of …, etc.
Supported RFCs/protocol flows/specification versions
Do not focus on “features that your service lacks”
Do not list the regions and environments here

If you need to document a lot of technical restrictions, create a dedicated topic (or even series of topics) as a sublevel of the What Is <Service Name>? section.

Document only bigger things here; smaller things like “password characters allowed” belong with the product. If it doesn’t have an impact on how the user works with the product, skip it.

Use the following standard formulation and format:

These are the general technical ranges of this service. There may be more, specific to the service plan you’ve chosen. See <link to service plans page in DC>.

<div> <div><em>Feature</em></div> <div><em>Quantity</em></div> <div><em>Details</em></div> <div><em>Additional Information</em></div> </div> <div> <div><em>Feature 1 (for example: Number of bindings)</em></div> <div> <p><em><number of/size of, range of…></em></p> <p><em>For example: 0-20</em></p> </div> <div> <p><em><Short description of the provided values></em></p> <p><em>For example:</em></p> <p><em>You can only have a limited number of bindings per instance</em></p> </div> <div> <p><em>Admin topic: …</em></p> <p><em>Dev topic: …</em></p> </div> </div> <div> <div><em>Feature 2</em></div> <div><em><number of/size of, range of…></em></div> <div><em><Short description of the provided values></em></div> <div><em><Short description of the provided values></em></div> </div>

warning

Do not document here the constraints specific to a service plan. Those are described in the Discovery Center.

Service plans: constraints imposed artificially by SAP. For example, in a Free tier plan for a DB service we allow for a limited numbers of tables with a limited number of entries in it.
General: relevant to the service implementation. For example, we support only a particular version of a communication protocol, or only a subset of features of a tech specification.