Technical Writing fuer SAP-Dokumentation: Anleitungen, APIs und mehr

kategorie

Karriere

Veröffentlicht

Feb 14, 2026

autor

Gute technische Dokumentation ist der Unterschied zwischen einer erfolgreichen Software und einem Albtraum fuer Anwender und Entwickler. Im SAP-Umfeld, wo Komplexitaet an der Tagesordnung ist, wird professionelles Technical Writing zu einer Kernkompetenz fuer jeden ABAP Cloud Entwickler.

Warum Technical Writing wichtig ist

Technische Dokumentation erfuellt mehrere kritische Funktionen:

Wissenstransfer: Neue Teammitglieder koennen sich schneller einarbeiten
Wartbarkeit: Code laesst sich besser verstehen und pflegen
Support-Reduktion: Weniger Rueckfragen bedeuten mehr Entwicklungszeit
Compliance: Viele Unternehmen fordern dokumentierte Systeme
Wiederverwendbarkeit: Gut dokumentierte Module werden oefter wiederverwendet

Die Kosten schlechter Dokumentation

Problem	Auswirkung
Fehlende Dokumentation	Wissensabhaengigkeit von Einzelpersonen
Veraltete Dokumentation	Falsche Annahmen, Bugs
Unstrukturierte Dokumentation	Lange Suchzeiten
Technisch ungenaue Dokumentation	Fehlimplementierungen

Dokumentationstypen in SAP-Projekten

1. API-Dokumentation

API-Dokumentation beschreibt die Schnittstellen deiner Software. In ABAP Cloud umfasst dies:

"! <p class="shorttext synchronized">Kundenverwaltungs-API</p>
"! Diese Klasse stellt Methoden zur Verwaltung von Kundendaten bereit.
"! <p>Verwendung:</p>
"! <ol>
"!   <li>Instanz ueber Factory-Methode erstellen</li>
"!   <li>Kundendaten mit get_customer lesen</li>
"!   <li>Aenderungen mit update_customer speichern</li>
"! </ol>
CLASS zcl_customer_api DEFINITION
  PUBLIC
  FINAL
  CREATE PRIVATE.

  PUBLIC SECTION.
    "! <p class="shorttext synchronized">Kundenstruktur</p>
    TYPES: BEGIN OF ty_customer,
             "! Eindeutige Kunden-ID
             customer_id   TYPE zde_customer_id,
             "! Vollstaendiger Name
             name          TYPE string,
             "! E-Mail-Adresse (validiert)
             email         TYPE string,
             "! Erstellungsdatum
             created_at    TYPE timestampl,
           END OF ty_customer.

    "! <p class="shorttext synchronized">Einzelnen Kunden lesen</p>
    "! @parameter iv_customer_id | Kunden-ID
    "! @parameter rs_customer | Kundendaten
    "! @raising zcx_customer_not_found | Kunde existiert nicht
    METHODS get_customer
      IMPORTING iv_customer_id    TYPE zde_customer_id
      RETURNING VALUE(rs_customer) TYPE ty_customer
      RAISING   zcx_customer_not_found.

    "! <p class="shorttext synchronized">Kunden aktualisieren</p>
    "! @parameter is_customer | Neue Kundendaten
    "! @raising zcx_validation_error | Ungueltige Daten
    METHODS update_customer
      IMPORTING is_customer TYPE ty_customer
      RAISING   zcx_validation_error.
ENDCLASS.

Elemente guter API-Dokumentation

Kurzbeschreibung: Was macht diese Klasse/Methode?
Parameter-Dokumentation: Typ, Bedeutung, Einschraenkungen
Rueckgabewerte: Was wird zurueckgegeben, wann?
Exceptions: Welche Fehler koennen auftreten?
Beispielcode: Typische Verwendung zeigen

2. Tutorial-Dokumentation

Tutorials fuehren Schritt fuer Schritt durch eine Aufgabe:

# RAP Business Object anlegen

In diesem Tutorial erstellst du ein vollstaendiges RAP Business Object
fuer eine Produktverwaltung.

## Voraussetzungen

- ADT 2024 oder neuer
- Zugriff auf ein ABAP Cloud System
- Basiswissen CDS Views

## Schritt 1: Datenbanktabelle anlegen

Erstelle zuerst die Datenbanktabelle fuer die Produkte:

```sql
@EndUserText.label: 'Produkte'
@AbapCatalog.enhancement.category: #NOT_EXTENSIBLE
define table ztproduct {
  key client      : abap.clnt not null;
  key product_id  : zde_product_id not null;
  product_name    : abap.char(100);
  price           : abap.curr(15,2);
  currency        : waers;
  created_by      : abap.uname;
  created_at      : timestampl;
}

Hinweis: Das Feld client wird automatisch vom System verwaltet.

Schritt 2: CDS View erstellen

[Naechster Schritt mit Erklaerung…]

#### Merkmale guter Tutorials

| Merkmal | Beschreibung |
|---------|--------------|
| Klares Ziel | Was kann der Leser am Ende? |
| Voraussetzungen | Was wird vorab benoetigt? |
| Nummerierte Schritte | Klare Reihenfolge |
| Erklaerungen | Warum, nicht nur was |
| Screenshots | Bei UI-Aktionen |
| Fehlerbehebung | Typische Probleme adressieren |

### 3. Referenz-Dokumentation

Referenzdokumentation ist ein Nachschlagewerk fuer alle Optionen:

```markdown
# @Consumption.valueHelpDefinition

Definiert eine Wertehilfe fuer ein CDS-Feld.

## Syntax

```sql
@Consumption.valueHelpDefinition: [{
  entity: {
    name: 'EntityName',
    element: 'ElementName'
  },
  qualifier: 'QualifierName',
  label: 'Dialogtitel',
  useForValidation: true|false,
  additionalBinding: [{...}]
}]

Parameter

Parameter	Typ	Pflicht	Beschreibung
entity.name	String	Ja	Name der Value Help Entity
entity.element	String	Nein	Schluesselelement der Entity
qualifier	String	Nein	Eindeutiger Bezeichner bei mehreren VH
label	String	Nein	Titel des Dialogs
useForValidation	Boolean	Nein	Eingabevalidierung aktivieren
additionalBinding	Array	Nein	Zusaetzliche Feldzuordnungen

additionalBinding

Parameter	Typ	Beschreibung
element	String	Feld in der VH-Entity
localElement	String	Feld in der aktuellen Entity
usage	Enum	#FILTER, #RESULT, #FILTER_AND_RESULT

Beispiele

Einfache Value Help

@Consumption.valueHelpDefinition: [{
  entity: { name: 'I_Currency', element: 'Currency' }
}]
Currency,

Mit Filterung

@Consumption.valueHelpDefinition: [{
  entity: { name: 'ZI_ProductVH', element: 'ProductId' },
  additionalBinding: [{
    element: 'Category',
    localElement: 'Category',
    usage: #FILTER
  }]
}]
ProductId,

Siehe auch

## Templates fuer ABAP-Dokumentation

### Template: Klassendokumentation

```abap
"! <p class="shorttext synchronized">[Kurze Beschreibung - max. 60 Zeichen]</p>
"!
"! <h2>Uebersicht</h2>
"! <p>[Ausfuehrliche Beschreibung der Klasse und ihres Zwecks]</p>
"!
"! <h2>Verwendung</h2>
"! <pre>
"! DATA(lo_instance) = zcl_my_class=>create( ).
"! DATA(lv_result) = lo_instance->process( iv_input = 'Test' ).
"! </pre>
"!
"! <h2>Abhaengigkeiten</h2>
"! <ul>
"!   <li>ZCL_HELPER_CLASS - Hilfsfunktionen</li>
"!   <li>ZIF_PROCESSOR - Verarbeitungs-Interface</li>
"! </ul>
"!
"! <h2>Autor</h2>
"! <p>Max Mustermann, Januar 2026</p>
CLASS zcl_my_class DEFINITION
  PUBLIC
  FINAL
  CREATE PRIVATE.

Template: Methoden-Dokumentation

"! <p class="shorttext synchronized">[Kurze Beschreibung der Methode]</p>
"!
"! <p>[Detaillierte Beschreibung: Was macht die Methode,
"! unter welchen Bedingungen, was sind Seiteneffekte?]</p>
"!
"! <h3>Beispiel</h3>
"! <pre>
"! TRY.
"!     DATA(lv_result) = lo_obj->method_name(
"!       iv_param1 = 'Wert1'
"!       iv_param2 = 100
"!     ).
"!   CATCH zcx_my_exception INTO DATA(lx_error).
"!     " Fehlerbehandlung
"! ENDTRY.
"! </pre>
"!
"! @parameter iv_param1 | [Beschreibung Parameter 1]
"! @parameter iv_param2 | [Beschreibung Parameter 2]
"! @parameter rv_result | [Beschreibung Rueckgabewert]
"! @raising zcx_my_exception | [Wann wird diese Exception geworfen?]
METHODS method_name
  IMPORTING iv_param1       TYPE string
            iv_param2       TYPE i DEFAULT 0
  RETURNING VALUE(rv_result) TYPE string
  RAISING   zcx_my_exception.

Template: README fuer ABAP-Paket

# [Paketname]

[Kurze Beschreibung: 1-2 Saetze]

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

1. Repository in abapGit klonen
2. Paket `ZPACKAGE` anlegen
3. Objekte pullen
4. Aktivieren

## Konfiguration

### Pflicht-Einstellungen

| Einstellung | Tabelle | Beschreibung |
|-------------|---------|--------------|
| SETTING_1 | ZCONFIG | ... |

### Optionale Einstellungen

[Beschreibung optionaler Konfigurationen]

## Verwendung

### Grundlegende Verwendung

```abap
DATA(lo_service) = zcl_service=>create( ).
DATA(lt_result) = lo_service->get_data( ).

Erweiterte Szenarien

[Komplexere Beispiele]

API-Referenz

ZCL_SERVICE - Hauptklasse
ZIF_PROCESSOR - Verarbeitungs-Interface

Beitragen

Fork erstellen
Feature-Branch anlegen
Aenderungen committen
Pull Request erstellen

Lizenz

[Lizenzinformationen]

## Gute vs. Schlechte Dokumentation

### Schlechtes Beispiel

```abap
" Diese Methode macht Dinge mit Kunden
" Parameter: id - die ID
METHOD process_customer.
  " Hole Daten
  SELECT * FROM zcustomer WHERE id = @iv_id INTO @DATA(ls_data).

  " Pruefe
  IF ls_data-status = 'A'.
    " Mache was
    ...
  ENDIF.
ENDMETHOD.

Probleme:

Vage Beschreibung (“macht Dinge”)
Keine Exception-Dokumentation
Keine Erklaerung der Geschaeftslogik
Inline-Kommentare wiederholen nur den Code

Gutes Beispiel

"! <p class="shorttext synchronized">Kundenbestellung verarbeiten</p>
"!
"! <p>Prueft den Kundenstatus und erstellt eine Bestellung, wenn der Kunde
"! aktiv ist. Bei inaktiven Kunden wird eine Benachrichtigung an den
"! Vertrieb gesendet.</p>
"!
"! <p><strong>Geschaeftsregel:</strong> Nur Kunden mit Status 'A' (aktiv)
"! duerfen Bestellungen aufgeben. Status 'I' (inaktiv) erfordert
"! Reaktivierung durch Vertrieb.</p>
"!
"! @parameter iv_customer_id | Eindeutige Kunden-ID aus dem CRM-System
"! @parameter iv_order_data | Bestelldaten inkl. Positionen
"! @parameter rv_order_id | Generierte Bestellnummer (Format: ORD-YYYYMMDD-NNNNN)
"! @raising zcx_customer_inactive | Kunde ist nicht aktiv (Status != 'A')
"! @raising zcx_order_validation | Bestelldaten sind ungueltig
METHOD process_customer_order.
  DATA(ls_customer) = get_customer_data( iv_customer_id ).

  " Geschaeftsregel: Nur aktive Kunden duerfen bestellen
  IF ls_customer-status <> 'A'.
    notify_sales_about_inactive_customer( iv_customer_id ).
    RAISE EXCEPTION TYPE zcx_customer_inactive
      EXPORTING customer_id = iv_customer_id.
  ENDIF.

  rv_order_id = create_order(
    is_customer = ls_customer
    is_order    = iv_order_data
  ).
ENDMETHOD.

Verbesserungen:

Klare Beschreibung des Zwecks
Geschaeftsregeln erklaert
Parameter vollstaendig dokumentiert
Exceptions mit Kontext
Hilfreiche Inline-Kommentare (Warum, nicht Was)

Tools fuer Dokumentation

1. ADT/ABAP Doc

ABAP Doc ist das native Dokumentationssystem:

"! @parameter iv_name | Der vollstaendige Name des Kunden
"! @raising zcx_validation | Name ist leer oder zu lang

Vorteile:

In ADT integriert
Automatische Vervollstaendigung
Synchronisiert mit Signatur

2. Markdown in abapGit

Fuer README-Dateien und uebergreifende Dokumentation:

/src
  /zcl_my_class.clas.abap
  /README.md          <-- Paket-Dokumentation
/docs
  /architecture.md    <-- Architektur-Uebersicht
  /api-reference.md   <-- API-Dokumentation

3. Knowledge Base Tools

Tool	Einsatzbereich
Confluence	Team-Dokumentation
Notion	Flexible Notizen
GitBook	Versionierte Doku
MkDocs	Markdown zu Website

4. Diagramm-Tools

Sequenzdiagramm (Mermaid):

sequenceDiagram
    participant Client
    participant RAP
    participant DB

    Client->>RAP: CREATE Order
    RAP->>RAP: Validation
    RAP->>DB: INSERT
    DB-->>RAP: OK
    RAP-->>Client: Order ID

Dokumentation pflegen

Das Problem veralteter Dokumentation

Veraltete Dokumentation ist schaedlicher als keine Dokumentation, weil sie:

Falsches Vertrauen erzeugt
Zu Fehlimplementierungen fuehrt
Zeit verschwendet

Strategien zur Aktualisierung

Documentation as Code
- Dokumentation im selben Repository wie Code
- Pull Requests muessen Doku-Updates enthalten
- Automatische Checks

Review-Prozess

Code Review Checkliste:
[ ] Neue Methoden dokumentiert?
[ ] Parameter-Aenderungen aktualisiert?
[ ] Beispiele noch aktuell?
[ ] Veraltete Referenzen entfernt?

Automatisierte Pruefungen

# GitHub Action
- name: Check documentation
  run: |
    # Pruefe auf undokumentierte public Methoden
    grep -r "PUBLIC SECTION" src/ | while read line; do
      # Pruefe ob ABAP Doc vorhanden
    done

Regelmaessige Reviews
- Quartalweise Dokumentations-Sprint
- Feedback von neuen Teammitgliedern einarbeiten
- Veraltete Abschnitte markieren

Integration in den Entwicklungsprozess

Definition of Done

Die Dokumentation sollte Teil der Definition of Done sein:

## Definition of Done - Dokumentation

Eine User Story ist dokumentationstechnisch fertig, wenn:

- [ ] Alle neuen Public-Methoden haben ABAP Doc
- [ ] Parameter und Exceptions sind dokumentiert
- [ ] Komplexe Geschaeftslogik ist kommentiert
- [ ] README ist aktualisiert (falls relevant)
- [ ] Architektur-Diagramme angepasst (falls relevant)

Pull Request Template

## Beschreibung
[Was wurde geaendert?]

## Dokumentation
- [ ] ABAP Doc fuer neue/geaenderte Methoden
- [ ] README aktualisiert
- [ ] Beispiele hinzugefuegt/aktualisiert

## Checkliste
- [ ] Code kompiliert
- [ ] Tests bestanden
- [ ] **Dokumentation geprueft**

Automatisierung mit ATC

" Custom ATC Check fuer Dokumentation
CLASS zcl_atc_doc_check DEFINITION
  INHERITING FROM cl_ci_test_root.

  PUBLIC SECTION.
    METHODS check_public_method_doc
      IMPORTING io_method TYPE REF TO if_method_info.
ENDCLASS.

CLASS zcl_atc_doc_check IMPLEMENTATION.
  METHOD check_public_method_doc.
    IF io_method->is_public( ) = abap_true AND
       io_method->get_documentation( ) IS INITIAL.
      add_finding(
        p_kind    = 'W'  " Warning
        p_text    = 'Public method without documentation'
        p_include = io_method->get_include( )
        p_line    = io_method->get_line( )
      ).
    ENDIF.
  ENDMETHOD.
ENDCLASS.

Best Practices Zusammenfassung

Dos

Prinzip	Beispiel
Zielgruppe kennen	Anfaenger vs. Experten
Beispiele verwenden	Konkreter Code
Aktuell halten	Mit Code-Aenderungen
Strukturiert schreiben	Klare Hierarchie
Konsistent bleiben	Einheitliche Formate

Don’ts

Fehler	Besser
”Selbsterklaerend”	Trotzdem dokumentieren
Code wiederholen	Zweck erklaeren
Zu viel Detail	Auf Wesentliches fokussieren
Jargon ohne Erklaerung	Begriffe definieren
Einmalig schreiben	Regelmaessig aktualisieren

Fazit

Gute technische Dokumentation ist eine Investition, die sich mehrfach auszahlt. Im SAP-Umfeld, wo Systeme oft jahrzehntelang im Einsatz sind, ist verstaendliche Dokumentation unverzichtbar.

Die wichtigsten Punkte:

Verschiedene Dokumentationstypen fuer verschiedene Zwecke nutzen
Templates fuer konsistente Qualitaet verwenden
Dokumentation als Teil des Codes behandeln
Regelmaessige Pflege einplanen
Automatisierung wo moeglich einsetzen

Mit diesen Grundlagen kannst du Dokumentation erstellen, die dein Team und zukuenftige Entwickler schaetzen werden.