Introduction

Tutorials are screenshot-illustrated, step-by-step guides. They are use case specific, should not be longer than 15-20 minutes, and help customers and partners to achieve a predefined goal. Tutorials don't provide all possibilities but give an example of the technology in use. In contrast to service documentation, they can be written in a rather approachable and informal tone of voice and allow for customer interaction as they invite users to share feedback via GitHub.

Use cases for technical tutorials:

Cover customer/user-specific questions.
Supports cross-product scenarios.
Allows for detailed process descriptions that go beyond the scope of the service documentation.
Used to advertise or pitch new concepts.

See How to Put Together a Mission (many tutorials packed together) for an overview of the components of a tutorial and a mission in the Tutorial Navigator.

SAP Tutorial Navigator

Getting Started

warning

The following tutorials are internally visible only: use (credentials: 20Digital20 / 20Digital20 ) to access them.

Prerequisites (see also Get Access on SAP Build Work Zone):

Create an external GitHub account. Once done, add your full name and SAP as your company to your new GitHub profile. Add an avatar/picture to your profile. Enable 2-factor authentication to your GitHub account, as described in GitHub's Configuring two-factor authentication.
Go to the SAP Open Source Portal and link your new GitHub account to your SAP identity.
On the next page in the Open Source Portal, scroll down, find 'sap-tutorials' and click Join next to the sap-tutorials organization.

information

Before you continue with the steps below, clarify in which repositories you should create your tutorials:

The common repositories for all tutorials are 'Tutorials-Contribution' (QA repository) and 'Tutorials' (production repository). In this case, you need to request permissions for 'Tutorials-Contribution' as described in the guidelines linked below.
For BTPX Foundation, there are dedicated repositories, therefore request permissions for 'btp-foundation-Contribution' (QA repository) and 'btp-foundation' (production repository) instead. Note, that the setup for BTPX Foundation, allows you to merge your own pull request in production without additional approval. Contact Svetoslav Pandeliev if you need access to the BTPX Foundation repositories.

Start Writing:

Set up your environment as described in Get Ready to Write Tutorials (2022).
If you are part of BTPX Foundation, use the respective repositories instead of the common ones described in this tutorial.
If you want to use Visual Studio Code as your Markdown editor, follow the setup as described in Use Visual Studio Code to Author Tutorials.
If you are part of BTPX Foundation, use the respective repositories instead of the common ones described in this tutorial.
Write your tutorial as described in Create new tutorial.
Add a validation question to a tutorial as described in Add Validation to a Tutorial.
Publish your tutorial to QA.
Publish your tutorial to production.
(only valid for 'btp-foundation') Merge your changes in production.
Combine existing tutorials into a mission or a group as described in Create a Tutorial Mission or Group.

Guidelines

When creating tutorials, consider the general guidelines as issued by SAP Community / SAP Learning in addition to the SAP BTP-specific guidelines.

General Guidelines

For more information on how to format and write tutorials, see the Style Guide.

SAP BTP-Specific Guidelines

Familiarize yourself with the specifics of writing tutorials for SAP BTP.

Creating Prerequisites

Do not describe the steps to get a trial account or an account with free service plans as part of your tutorial. Instead, link to the existing tutorials in your Prerequisites section, as needed:

Get a Free Account on SAP BTP Trial or Mission: Set Up an SAP BTP Account for Tutorials

Example: Free Tier Prerequisites in Tutorials

Specifying Environments

Specify whether your tutorial can only be executed in a certain environment: Neo, Cloud Foundry, etc. You can mention that as a prerequisite.

Trial Landscape: Free Tier

Every tutorial needs to run on a trial landscape (see: Tutorial Navigator guidelines). If your service, does not offer a trial version, you need to tag your tutorial accordingly: "Requires Customer License".

Using SUI Graphics

Instead of using raw screenshots, we recommend using Simplified User Interface (SUI) Graphics. They combine the following advantages:

future-proof
pleasing to the eye
effective

For more information on the concept, guidelines, and examples, see SUI Graphics.

Example: SUI Graphics

Support

Visit the Tutorial Navigator Workspace: SAP Tutorial Navigator
Find help in the community: Tutorial Navigator Forum
Report an issue with the tutorial plug-in: Issue Reporting PlugIn
Ask the guideline owner: Joshua Margo
For BTPX Foundation, contact: Svetoslav Pandeliev

Customer Feedback & Analytics

You can request access to a dashboard for monitoring tutorials, including analytics, starts, completions, survey feedback:

Access the dashboard via web or Microsoft Teams: Tutorial Dashboard (request needs to be made)
Access a presentation with detailed description on how to work with the dashboard.
Contact: Viliana Encheva-Manolova