Meta Tutorials — the tutorials that teach you to write tutorials
The sap-tutorials/meta-tutorials-Contribution repo holds the platform's own "how to author" content: a set of tutorials that walk a new author from an empty machine all the way through writing, validating, and publishing a tutorial.
Because they live in a *-Contribution repo, they are not published to the public catalog at developers.sap.com/tutorials/. Instead they are exposed on the QA author-preview channel at /tutorials-qa/<slug>, so authors can read them exactly as a reader would — rendered by the same Hugo pipeline, before anything reaches production. See QA Channel Bootstrap for how that channel is wired.
Access. The QA channel is XSUAA-gated and needs the
Tutorial.Authorscope. Open the links below in a browser where you're logged in to the platform — an unauthenticated request lands on the login shell, not the page.
QA base URL (production deployment):
https://tutorial-system-prod-tutorials-approuter.cfapps.eu10-005.hana.ondemand.com/tutorials-qa/<slug>Recommended path
Read these roughly in order. Steps 1–2 orient you; 3 sets up tooling; 4–7 are the core author loop (write → validate → publish); 8+ are for groups, files, and day-to-day monitoring.
1. Orientation
| # | Tutorial | Time | What you'll learn |
|---|---|---|---|
| 1 | The Big Picture on Tutorials | 30 min | The purpose of our tutorials and how the whole authoring system fits together. |
| 2 | Configure your machine for Tutorial Authoring | 30 min | How to plan for writing tutorials and get your local environment ready. |
2. Choose and set up your editor
Pick the toolchain you'll author in. VS Code + Sage is the current recommendation; the Atom helper tutorials are legacy and only needed if you're maintaining older workflows.
| # | Tutorial | Time | What you'll learn |
|---|---|---|---|
| 3 | Use Visual Studio Code to Author Tutorials | 10 min | How to author .md and .vr files in Visual Studio Code. |
| 4 | Install and Set Up the Sage Tutorial Authoring Extension | 30 min | How to download, install, and use the Sage VS Code extension for author-time linting and preview. |
| — | Prepare Atom Editor for Individual Repos (v2 parser) | 10 min | (Legacy) Prepare the Atom editor to write and publish with individual GitHub repositories. |
| — | Prepare Atom Editor for Individual Repos | 10 min | (Legacy, pre-v2) Same as above for the original parser. |
3. Write
| # | Tutorial | Time | What you'll learn |
|---|---|---|---|
| 5 | Create a Tutorial | 15 min | How to create a new tutorial from scratch. |
| 6 | Update an Existing Tutorial (v2 parser) | 5 min | How to update a tutorial that's already published. |
| — | Examples of Markdown Syntax for v2 Parser | 10 min | A reference of every markdown/callout/validation construct the v2 parser supports. Keep it open while you write. |
| — | (Optional) Create a new tutorial using the DITA CMS (v2 parser) | — | For UA information developers: author from the DITA CMS using the 1DX markdown output type, then deploy to QA. |
4. Validate
| # | Tutorial | Time | What you'll learn |
|---|---|---|---|
| 7 | Add Validation to a Tutorial (v2 parser) | 10 min | How to create a rules file with validation steps so readers can check their work. |
5. Publish and manage
| # | Tutorial | Time | What you'll learn |
|---|---|---|---|
| 8 | Publish a Tutorial to Production (v2 parser) | 5 min | How to move your tutorial from your fork through to production. |
| 9 | Delete a Tutorial from QA (v2 parser) | 5 min | How to delete a tutorial from QA that is not yet in production. |
| 10 | Groups and Missions | 10 min | How to compose and request a tutorial mission or group. |
6. Supporting tools
| # | Tutorial | Time | What you'll learn |
|---|---|---|---|
| 11 | Upload Files to FCMS for Developer Downloads | 10 min | How to gain access to FCMS and upload downloadable assets for your tutorial. |
| 12 | Introduction to the Tutorial Dashboard | 10 min | How to access the Tutorial Dashboard to monitor the health of your content. |
7. AI-assisted authoring
Optional. Once you're comfortable with hand-authored validation (step 7 above), these tutorials show how to let AI generate or grade your quizzes.
| # | Tutorial | Time | What you'll learn |
|---|---|---|---|
| 13 | Use AUTOAUTHOR to Generate Quiz Questions with AI | 15 min | How the [AUTOAUTHOR_*] directives generate quiz questions at build time from step content — or, with [AUTOAUTHOR_VIDEO_*], from a YouTube video's transcript. |
| 14 | Use CODECHECK to AI-Grade Reader Code | 15 min | How [CODECHECK_N] gives readers a code editor and grades their submission against a goal you describe, not an exact string. |
| 15 | Use VALIDATE to AI-Grade Free-Text Answers | 15 min | How ai-judged grading accepts open-ended answers in the reader's own words, judged against a server-side reference answer. |
Notes and caveats
- 16 meta tutorials are live on the QA channel and verified reachable (2026-07-25).
- The three AI-authoring tutorials are being restored.
use-autoauthor-to-generate-quiz-questions,use-codecheck-to-ai-grade-reader-code, anduse-validate-to-ai-grade-free-text-answerspreviously returned 404 because their source markdown was missing from themeta-tutorials-Contributionrepo (onlyrules.vrremained). The markdown is restored in meta-tutorials-Contribution#11 (issue #2374); once that PR merges and the QA channel rebuilds, the three entries in §7 above resolve. Until then they may still 404. - The two Atom editor tutorials are legacy. New authors should use VS Code + Sage and can skip them.
Related
- Writing tutorials — this repo's own author workflow (fetch → parse → Hugo → HANA)
- Repo / group owners — reviewing PRs and managing
sap-tutorialsrepos - QA Channel Bootstrap — how the
/tutorials-qa/*preview channel is set up - Sage VS Code extension — author-time linting and preview