Overview

These guidelines apply to the entire SAP BTP: core, environments, and services. Please follow them when preparing release notes for the platform. Our goal is to achieve and maintain consistency and high-quality deliverables.

You can find instructions about how to provide content for the new design in Tasks for the Authors. These guidelines are for the values to provide in your component table in Ixiasoft and the examples show how the output looks on SAP Help Portal. The output can show the attributes in a list and a table view. However, the guidelines and examples below show the default list view.

We publish all platform-related release notes on UACP at What's New.

Please follow these major guidelines when you prepare release notes for the What's New viewer:

• Always include the action for required and recommended actions with information about WHAT the action is and HOW to achieve it.
• Wherever applicable, add links for more information. An exception could be, for example, trivial minor updates or self-explanatory changes that require no action on behalf of the customer.
• Keep the release note short. If you need to describe lengthy procedures, use cases, concepts or background info, add links instead.

If the release note becomes too lengthy but there is no relevant topic (in another deliverable) to link to, create a dedicated topic in the central WNV map. Shorten the release note text and add a link to that topic for more information.

Responsibility

It is the responsibility of the UA developer of each team to apply these guidelines.

If you are a product owner of a team that does not have a UA developer, please familiarize yourself with and follow these guidelines. Once you have prepared and reviewed your release notes, you can send them to us for an additional check.

Pattern

Use the following pattern for all notes:

These columns look like this in the list view:

- <Title>

<Description>

<Environment> • <Action> • <Type>

Customer Feedback

Announce an improvement that is the result of customer feedback.

Experimental Features

Describe experimental features.

You first create a topic following the instructions in Experimental Features. You then refer to the topic in the release note description and add the [Experimental] tag at the end. Furthermore, you use the Lifecycle value .

Beta Features

Describe beta features.

You first create a topic following the instructions in Beta Features. Then refer to the topic in the release note description and add the [Beta] tag at the end. Furthermore, you use the Lifecycle value .

Action Definition

You have to add a value (Required, Recommended, or Info only) in the Action column that specifies the level of disruption and if an action is required by the customer. For more information, see Filter and Label Descriptions. When an action is required or recommended, please add the following paragraph at the end of the description:

Action: <include information about . In case of complex actions and too much information in the release note, provide links to topics describing what the action is and how the customer has to achieve it.>

:

• Version Update
• Restart Notifications
• Customer Applications

Fix

Announce that a bug is fixed. Please use something more specific for the Title (try to avoid repeating the Technical Component in the Title).

Version Update

Announce that an old version is replaced with a new one.

New Version Added

Announce that a new version is added to the list of available versions.

New Component Added

Announce that a new component (environment, service, feature, etc.) is added to the list of available components.

New Region Added

Announce that a new region is available.

Component Renamed

You announce that your component (service) is renamed.

Please also replace the old component name in the column with the new name for the entries that have been created before the actual renaming took place.

Old Feature, Resource, or Version Deprecated or Deleted

Announce that something is discontinued and will be deleted. The date should be the actual date of the deprecation. For example, you announce today that a feature will be deprecated in 2 months. Then, the date of the release note will be for after two months.

You should prepare another release note with lifecycle Deleted when the version is to be completely removed. The date should be the actual date of the deletion.

Changed Feature in Existing Component

Announce that an existing feature is changed.

Old Version Is Out of Maintenance

Announce that a version is not longer maintained or supported.

Announcement of Existing Old Components

You should announce that an old component still exists even though it doesn't have release notes for the current What's New viewer. For such an announcement, you just inform customers that there have been no new release notes yet. You do this by adding a new row with the button in loio4917542b0c9749739b955a33b2453077. You then provide the values in the and columns. Everything else is pre-configured with the template.

Announcement of Upgrades or Downtimes

You can find the harmonized release calendar for the cloud products at Intelligent Enterprise Suite: Harmonized release calendar for SAP Cloud products. It is recommended that you refer to this note or to the help topic section when announcing any upgrades or downtimes. Please also follow these guidelines:

• If the release note is about an upgrade, include the Upgrade term in the title. Example: SAPUI5 - Upgrade to Version 1.102.0
• Publish such a release note ahead of time as a preview. It is fine if it's even published a month ahead.
• If there is a downtime, please include it in the Description. Also, mention under the action that customers must plan for the downtime ahead of time. Example: Action: Plan for this downtime as soon as possible by performing the following tasks:...
• Use Action with value Recommended or Required as you explain in the Description what must be done and how.

Release Notes per Specific IaaS Region

When you provide release notes for a specific region such as China (Shanghai) or NS2, you need to add the referable content suffix from loioace70e70443e446caa330ec48db61b90 to the title.

:

- Deprecating Shared Domains [China (Shanghai) Region]

The shared domains are now removed from Alibaba Cloud Landscapes. Till now, when the domain was not specified for an application, the MTA deployment service got the first shared domain and used it. After the removal of shared domains in Alibaba Cloud, the application must be configured and the parameter domain must be specified. The MTA deployment service will not resolve the ${default-domain} placeholder on these landscapes any longer. If the placeholder is being used, you should change it to ${domain} placeholder and additionally specify a domain for each module. Alternatively, the routes parameter could be used which requires the domain to be part of the route.

Standards

• Follow the S&Gs and the PCA guidelines. See Standards and Guidelines for User Assistance at SAP. You can find PCA guidelines on the PCA Jam site.
• Use the correct and "official" product/service offering names, according to the Approved Names list.

Links

• Place links on words that tell users what they will see on the other end of the link.
• Do not anchor a link on words like here, click here, more info. It is ambiguous.
• Introduce links with See... instead of For more information, see...
• Provide references to the official documentation instead of blog posts or other sources.
• Link to the most specific topic available. You can also create an additional topic and include it in the What's New buildable map (loio311de33b9caf4df1a64d7d58213afabe) under Referenced Topics. However, the recommendation is to include such topics in your guide.
• Cite the whole title of the referenced document.
• Keep the number of links in a single note small. Try to give one link only.
• Do not forget to provide a link. The purpose of a note is to state that something has been done/changed. There might be users who want to learn more. These people will benefit from a direct link to the details.

Style

• Use active voice as much as possible.
• Use the second person pronoun you. Avoid using the third person.
• Keep notes short (the recommendation is one or two sentences).
• Provide the most essential information in the note.
• Leave details for a reference topic and link to it.
• Use short sentences.
• Choose short words.

Terminology

Avoid using the following terminology:

• Self-service - the term self-service does not make sense in the documentation. Everything that users do in the cockpit is a self-service. There is no need to complicate the text so much.
• Use the terms approved in Glossary or SAPterm.

Consistency

• Stick to the same style across all your notes and in all release notes by others. For example, do not write the first two release notes with one style, and the others with another.
• Across all SAP BTP notes: Check the other notes and try to stick to the approach and style that they are using.

Proper Wording and Grammar

• Be precise. When you describe a fix that leads to an improvement, provide qualitative information.
• No errors. No spelling errors. No grammatical errors. No factual errors. There is nothing more belittling for an entity (company or person) than a text with errors. So please, check spelling, grammar, and facts. Also, use our copy editor Rachi Ofir.
• Choose the right words. See Example 2 in Examples with Recommendations for Improvements.

Examples with Recommendations for Improvements

Example 1

- Validation Step Introduced for JSON-to-XML Converter

The JSON-to-XML converter now checks for each JSON member name if its name can be converted into a valid XML element or attribute name. If this is not the case, an exception is thrown.

Action: Check if your existing integration scenarios have processed invalid XML element or attribute names before.

The introduced enhancement can have an impact on existing integration flows containing the previous version of the JSON-to-XML converter.

Scenarios that have processed invalid XML element or attribute names before can now result in an error due to the newly introduced validation check. If that's the case, you can contact SAP to withdraw the enhancement.

See:

• Limitations for JSON to XML Conversion
• 3112970 - JSON-to-XML Converter Exception Caused by Invalid JSON Member Name (Knowledge Base Article)

Neo, Cloud Foundry • Recommended • General Availability • Changed

Issues

This release note describes the recommended action well, but it does not clarify how the customer has to achieve it: .

Better

- Validation Step Introduced for JSON-to-XML Converter

The JSON-to-XML converter now checks for each JSON member name if its name can be converted into a valid XML element or attribute name. If this is not the case, an exception is thrown.

Action: Check if your existing integration scenarios have processed invalid XML element or attribute names before.

The introduced enhancement can have an impact on existing integration flows containing the previous version of the JSON-to-XML converter.

Scenarios that have processed invalid XML element or attribute names before can now result in an error due to the newly introduced validation check. If that's the case, you can contact SAP to withdraw the enhancement with an incident by following the process at .

See:

• Limitations for JSON to XML Conversion
• 3112970 - JSON-to-XML Converter Exception Caused by Invalid JSON Member Name (Knowledge Base Article)

Neo, Cloud Foundry • Recommended • General Availability • Changed

Example 2

- New Commercial Model for SAP BTP Services

SAP is now offering a new consumption-based commercial model, located to find, try, buy, consume, and pay for the usage of a set of eligible SAP cloud services.

To use the consumption-based commercial model, your organization first needs to sign a Cloud Platform Enterprise Agreement (CPEA) with SAP and make a prepaid investment in cloud credits. Your organization does not have to purchase specific subscriptions in advance for the services that you plan to use. All eligible services are entitled, but nothing is charged until usage begins and then you pay only for the actual usage of the eligible services.

When you set up an account with the consumption-based model, there are no predefined quotas to limit usage. You assign entitlements to services in subaccounts to regulate and monitor how the eligible cloud services are used throughout the organization.

See and .

Neo, Cloud Foundry • Info only • General Availability • Announcement

Points for Improvement

• The type should be New instead of Announcement.
• The title is too long.
• The title states SAP BTP, which is obvious.
• It states the type, which is mentioned above.
• It is better to state the nature of the model. For example, Consumption-Based Commercial Model.
• The content is too long. It contains 143 words and 888 characters, which is hard to scan.
• We should avoid speaking about SAP in the third person. That might be necessary only if we are mentioning a third-party vendor. Say "We" instead.
• It might be better to simplify the text. For example, “…a new consumption-based commercial model located to find, try, buy, consume, and pay for the usage of a set in Amsterdam, Europe.” Maybe, we can say here, "...a new consumption-based commercial model offered in Amsterdam, Europe to test and pay for the usage."
• Some details might be omitted and included in the referenced topic. For example, “To use the consumption-based commercial model, your organization first needs to sign an SAP BTP Enterprise Agreement with SAP and make a prepaid investment in cloud credits.”
• The text should be copy edited by Rachi Ofir. See steps 2 and 3 at Steps for Authors.

The following text is shorter, faster to read, more focused, and conveys better the introduction of a new commercial model.

- Services

The new commercial model allows you to prepay a certain amount and then expend it over time for the services that you use. Nothing is charged until usage begins, and then you pay only for the actual usage. There are no predefined quotas. You assign services in subaccounts to regulate and monitor how the services are used. See .

Neo, Cloud Foundry • Info only • General Availability • New

Example 3

- Inventory

You can now move your feature flags inventory to a new instance with the following:

• Export the data from the old service instance
• Provide the exported data as configuration when you create a new service instance

More details about this process can be found here <link to documentation>.

Neo • Info only • General Availability • New

Points for Improvement

• The word “move” implies that after the action the inventory will not be at the original place. This is not true. The inventory is in fact copied to a new service instance.
• We use bullets, yet the bullets represent two consecutive steps. If we use a list here, it must be numbered. Since these are just two steps, it is perfectly OK to use regular sentences.
• For the link, use See <link to documentation>.

Better

- Feature-Flag Inventory

You can use existing feature-flag inventories in new service instances. First, export the desired inventory from an instance. Then, when creating the new instance, provide the exported data as configuration. See <link to documentation>.

Neo • Info only • General Availability • New

Example 4

- Subscriptions

Using the cockpit, you can manage your subscriptions to SaaS multitenant business applications in the Cloud Foundry environment. A new entry, Subscriptions, is available in the cockpit navigation menu in your Cloud Foundry subaccount. This screen lists all the SaaS business applications, for which you have purchased a license from SAP, in your Cloud Foundry account. Here, you can also view the applications that you currently subscribed to, create and remove subscriptions, and launch subscribed applications.

You can use the cockpit to view the list of application roles that have been defined for a subscribed application by navigating to the tab of the subscribed application. See and.

Cloud Foundry • Info only • General Availability • New

Points for Improvement

• Some terminology might not be correct. For example, Cloud Foundry subaccount, cockpit navigation menu, or SaaS business applications. We should check with Brand Voice or SAPterm what terms are acceptable.
• We should refer to topics that are relevant for or describe the new feature. It is not necessary to link to a general concept topic.

Better

- Subscriptions

Subscriptions are now available in the Cloud Foundry environment. The page lists all applications to which your subaccount is subscribed.

You can also view the list of application roles defined for a subscribed application: go to the tab of the subscribed application. See .

Cloud Foundry • Info only • General Availability • New

Example 5

- Database Explorer

The SAP HANA database explorer is integrated into both the SAP HANA cockpit service and the SAP Web IDE for SAP HANA service. The database explorer allows you to execute SQL statements and database procedures, query information about the database, and view information about database catalog objects. See SAP Note 2485954 . For more information about the database explorer for the Cloud Foundry environment, see .

Cloud Foundry • Info only • General Availability • New

Points for Improvement

• What is the news here? How is it related to the platform? It is not clear what we are saying.
• The link to “SAP Note 2485954” is broken. We need to replace “%23” with “#” in the URL. “SAP Note 2485954” does not provide anything additional. It gives the exact same two sentences that we have given here. What is the point of referencing the note?
• Topic “SAP HANA Database Explorer” does not exist. The link points to a topic called “SAP HANA Database Explorer and SQL Analyzer”, which topic is virtually empty. Maybe it will be better to link to About the SAP HANA Database Explorer and the SQL Analyzer because that topic explains what is what.

Better

- Database Explorer

The SAP HANA database explorer is now available for use with SAP HANA cockpit and SAP Web IDE for SAP HANA. The database explorer allows you to execute SQL statements and database procedures, query information about the database, and view information about database catalog objects. See .

Cloud Foundry • Info only • General Availability • New

Example 6

- Changes to Business Rules regarding Account Assignment

You can now differentiate between leg 1 and leg 2 for the account assignment attributes in the input structure of all relevant business rules. The following rules are subject to this change:

• Decision for Trade Request Routing Category
• Decision for Intercompany Trading Scenario
• Decision for Foreign Exchange Instrument Category
• Derivation of Trading Partners
• Decision for Foreign Exchange Instrument Category
• Decision for Trading Scenario
• Decision for Markup or Markdown
• Decision for Quotation Source

If you have configured any of these rules with conditions based on one of the following assignment fields, you need to activate the rule by selecting the rule and .

Impacted account assignment fields:

• hedgingClassification
• hedgingArea
• portfolio
• onBehalfOfCompany
• profitCenter
• costCenter
• wbsElement
• businessArea
• segment
• countryCode
• hedgeRequestId
• externalReference
• assignment
• internalReference
• characteristics

Additionally, you can differentiate between leg 1 and leg 2 for the account assignment attributes in the input and result structure for the business rule.

Action: Make the relevant changes in the business rules and activate the rules if necessary.

Cloud Foundry • Recommended • General Availability • Changed

Points for Improvement

• This note is too long and our customers complain about having to skim too much content. The author should move the lengthy text to a new topic, or even two topics, and refer to them. The purpose of a release note isn't to explain all of the details of a functionality, but just to inform the user about the feature or concept.
• There is no reference for more information. Our customers always expect to find additional information.

Better

- Changes to Business Rules Regarding Account Assignment

You can now differentiate between leg 1 and leg 2 for the account assignment attributes in the input structure of all relevant business rules. See .

Action: Make the relevant changes in the business rules and activate the rules if necessary. See .

Cloud Foundry • Recommended • General Availability • Changed