Technical Writing pour la documentation SAP : Guides, APIs et plus

Catégorie

Karriere

Publié

14. Feb. 2026

Auteur

Une bonne documentation technique fait la difference entre un logiciel reussi et un cauchemar pour les utilisateurs et les developpeurs. Dans l’environnement SAP, ou la complexite est la norme, le Technical Writing professionnel devient une competence cle pour tout developpeur ABAP Cloud.

Pourquoi le Technical Writing est important

La documentation technique remplit plusieurs fonctions critiques :

Transfert de connaissances : Les nouveaux membres de l’equipe peuvent s’integrer plus rapidement
Maintenabilite : Le code peut etre mieux compris et maintenu
Reduction du support : Moins de questions signifie plus de temps de developpement
Conformite : De nombreuses entreprises exigent des systemes documentes
Reutilisabilite : Les modules bien documentes sont plus souvent reutilises

Les couts d’une mauvaise documentation

Probleme	Impact
Documentation manquante	Dependance aux connaissances individuelles
Documentation obsolete	Hypotheses erronees, bugs
Documentation non structuree	Temps de recherche longs
Documentation techniquement imprecise	Implementations incorrectes

Types de documentation dans les projets SAP

1. Documentation API

La documentation API decrit les interfaces de votre logiciel. En ABAP Cloud, cela inclut :

"! <p class="shorttext synchronized">API de gestion des clients</p>
"! Cette classe fournit des methodes pour la gestion des donnees clients.
"! <p>Utilisation :</p>
"! <ol>
"!   <li>Creer une instance via la methode factory</li>
"!   <li>Lire les donnees client avec get_customer</li>
"!   <li>Sauvegarder les modifications avec update_customer</li>
"! </ol>
CLASS zcl_customer_api DEFINITION
  PUBLIC
  FINAL
  CREATE PRIVATE.

  PUBLIC SECTION.
    "! <p class="shorttext synchronized">Structure client</p>
    TYPES: BEGIN OF ty_customer,
             "! ID client unique
             customer_id   TYPE zde_customer_id,
             "! Nom complet
             name          TYPE string,
             "! Adresse email (validee)
             email         TYPE string,
             "! Date de creation
             created_at    TYPE timestampl,
           END OF ty_customer.

    "! <p class="shorttext synchronized">Lire un client</p>
    "! @parameter iv_customer_id | ID client
    "! @parameter rs_customer | Donnees client
    "! @raising zcx_customer_not_found | Le client n'existe pas
    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">Mettre a jour un client</p>
    "! @parameter is_customer | Nouvelles donnees client
    "! @raising zcx_validation_error | Donnees invalides
    METHODS update_customer
      IMPORTING is_customer TYPE ty_customer
      RAISING   zcx_validation_error.
ENDCLASS.

Elements d’une bonne documentation API

Description courte : Que fait cette classe/methode ?
Documentation des parametres : Type, signification, restrictions
Valeurs de retour : Qu’est-ce qui est retourne, quand ?
Exceptions : Quelles erreurs peuvent survenir ?
Code exemple : Montrer l’utilisation typique

2. Documentation tutoriel

Les tutoriels guident etape par etape a travers une tache :

# Creer un RAP Business Object

Dans ce tutoriel, vous allez creer un RAP Business Object complet
pour une gestion de produits.

## Prerequis

- ADT 2024 ou plus recent
- Acces a un systeme ABAP Cloud
- Connaissances de base des CDS Views

## Etape 1 : Creer la table de base de donnees

Creez d'abord la table de base de donnees pour les produits :

```sql
@EndUserText.label: 'Produits"
@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;
}

Note : Le champ client est gere automatiquement par le systeme.

Etape 2 : Creer la CDS View

[Etape suivante avec explication…]

#### Caracteristiques des bons tutoriels

| Caracteristique | Description |
|-----------------|-------------|
| Objectif clair | Que peut faire le lecteur a la fin ? |
| Prerequis | Qu'est-ce qui est necessaire au prealable ? |
| Etapes numerotees | Ordre clair |
| Explications | Pourquoi, pas seulement quoi |
| Captures d'ecran | Pour les actions UI |
| Depannage | Traiter les problemes typiques |

### 3. Documentation de reference

La documentation de reference est un ouvrage de consultation pour toutes les options :

```markdown
# @Consumption.valueHelpDefinition

Definit une aide a la saisie pour un champ CDS.

## Syntaxe

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

Parametres

Parametre	Type	Obligatoire	Description
entity.name	String	Oui	Nom de l’entite Value Help
entity.element	String	Non	Element cle de l’entite
qualifier	String	Non	Identifiant unique pour plusieurs VH
label	String	Non	Titre du dialogue
useForValidation	Boolean	Non	Activer la validation de saisie
additionalBinding	Array	Non	Associations de champs supplementaires

additionalBinding

Parametre	Type	Description
element	String	Champ dans l’entite VH
localElement	String	Champ dans l’entite actuelle
usage	Enum	#FILTER, #RESULT, #FILTER_AND_RESULT

Exemples

Value Help simple

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

Avec filtrage

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

Voir aussi

## Templates pour la documentation ABAP

### Template : Documentation de classe

```abap
"! <p class="shorttext synchronized">[Description courte - max. 60 caracteres]</p>
"!
"! <h2>Vue d'ensemble</h2>
"! <p>[Description detaillee de la classe et de son objectif]</p>
"!
"! <h2>Utilisation</h2>
"! <pre>
"! DATA(lo_instance) = zcl_my_class=>create( ).
"! DATA(lv_result) = lo_instance->process( iv_input = 'Test' ).
"! </pre>
"!
"! <h2>Dependances</h2>
"! <ul>
"!   <li>ZCL_HELPER_CLASS - Fonctions utilitaires</li>
"!   <li>ZIF_PROCESSOR - Interface de traitement</li>
"! </ul>
"!
"! <h2>Auteur</h2>
"! <p>Jean Dupont, Janvier 2026</p>
CLASS zcl_my_class DEFINITION
  PUBLIC
  FINAL
  CREATE PRIVATE.

Template : Documentation de methode

"! <p class="shorttext synchronized">[Description courte de la methode]</p>
"!
"! <p>[Description detaillee : Que fait la methode,
"! dans quelles conditions, quels sont les effets de bord ?]</p>
"!
"! <h3>Exemple</h3>
"! <pre>
"! TRY.
"!     DATA(lv_result) = lo_obj->method_name(
"!       iv_param1 = 'Valeur1"
"!       iv_param2 = 100
"!     ).
"!   CATCH zcx_my_exception INTO DATA(lx_error).
"!     " Gestion d'erreur
"! ENDTRY.
"! </pre>
"!
"! @parameter iv_param1 | [Description Parametre 1]
"! @parameter iv_param2 | [Description Parametre 2]
"! @parameter rv_result | [Description valeur de retour]
"! @raising zcx_my_exception | [Quand cette exception est-elle levee ?]
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 pour package ABAP

# [Nom du package]

[Description courte : 1-2 phrases]

## Fonctionnalites

- Fonctionnalite 1
- Fonctionnalite 2
- Fonctionnalite 3

## Installation

1. Cloner le repository dans abapGit
2. Creer le package `ZPACKAGE`
3. Tirer les objets
4. Activer

## Configuration

### Parametres obligatoires

| Parametre | Table | Description |
|-----------|-------|-------------|
| SETTING_1 | ZCONFIG | ... |

### Parametres optionnels

[Description des configurations optionnelles]

## Utilisation

### Utilisation de base

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

Scenarios avances

[Exemples plus complexes]

Reference API

ZCL_SERVICE - Classe principale
ZIF_PROCESSOR - Interface de traitement

Contribuer

Creer un fork
Creer une branche de fonctionnalite
Commiter les modifications
Creer une Pull Request

Licence

[Informations de licence]

## Bonne vs. Mauvaise documentation

### Mauvais exemple

```abap
" Cette methode fait des choses avec les clients
" Parametre : id - l'ID
METHOD process_customer.
  " Recuperer les donnees
  SELECT * FROM zcustomer WHERE id = @iv_id INTO @DATA(ls_data).

  " Verifier
  IF ls_data-status = 'A'.
    " Faire quelque chose
    ...
  ENDIF.
ENDMETHOD.

Problemes :

Description vague (“fait des choses”)
Pas de documentation des exceptions
Pas d’explication de la logique metier
Les commentaires inline repetent juste le code

Bon exemple

"! <p class="shorttext synchronized">Traiter commande client</p>
"!
"! <p>Verifie le statut du client et cree une commande si le client
"! est actif. Pour les clients inactifs, une notification est envoyee
"! aux ventes.</p>
"!
"! <p><strong>Regle metier :</strong> Seuls les clients avec le statut 'A' (actif)
"! peuvent passer des commandes. Le statut 'I' (inactif) necessite
"! une reactivation par les ventes.</p>
"!
"! @parameter iv_customer_id | ID client unique du systeme CRM
"! @parameter iv_order_data | Donnees de commande incluant les postes
"! @parameter rv_order_id | Numero de commande genere (Format : ORD-YYYYMMDD-NNNNN)
"! @raising zcx_customer_inactive | Le client n'est pas actif (Statut != 'A')
"! @raising zcx_order_validation | Les donnees de commande sont invalides
METHOD process_customer_order.
  DATA(ls_customer) = get_customer_data( iv_customer_id ).

  " Regle metier : Seuls les clients actifs peuvent commander
  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.

Ameliorations :

Description claire de l’objectif
Regles metier expliquees
Parametres entierement documentes
Exceptions avec contexte
Commentaires inline utiles (Pourquoi, pas Quoi)

Outils pour la documentation

1. ADT/ABAP Doc

ABAP Doc est le systeme de documentation natif :

"! @parameter iv_name | Le nom complet du client
"! @raising zcx_validation | Le nom est vide ou trop long

Avantages :

Integre dans ADT
Completion automatique
Synchronise avec la signature

2. Markdown dans abapGit

Pour les fichiers README et la documentation transversale :

/src
  /zcl_my_class.clas.abap
  /README.md          <-- Documentation du package
/docs
  /architecture.md    <-- Vue d'ensemble de l'architecture
  /api-reference.md   <-- Documentation API

3. Outils Knowledge Base

Outil	Domaine d’utilisation
Confluence	Documentation d’equipe
Notion	Notes flexibles
GitBook	Documentation versionnee
MkDocs	Markdown vers site web

4. Outils de diagrammes

Diagramme de sequence (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

Maintenir la documentation

Le probleme de la documentation obsolete

Une documentation obsolete est plus nuisible que pas de documentation, car elle :

Cree une fausse confiance
Conduit a des implementations incorrectes
Fait perdre du temps

Strategies de mise a jour

Documentation as Code
- Documentation dans le meme repository que le code
- Les Pull Requests doivent inclure des mises a jour de documentation
- Verifications automatiques

Processus de revue

Checklist Code Review :
[ ] Nouvelles methodes documentees ?
[ ] Changements de parametres mis a jour ?
[ ] Exemples encore actuels ?
[ ] References obsoletes supprimees ?

Verifications automatisees

# GitHub Action
- name: Check documentation
  run: |
    # Verifier les methodes publiques non documentees
    grep -r "PUBLIC SECTION" src/ | while read line; do
      # Verifier si ABAP Doc est present
    done

Revues regulieres
- Sprint documentation trimestriel
- Integrer les retours des nouveaux membres de l’equipe
- Marquer les sections obsoletes

Integration dans le processus de developpement

Definition of Done

La documentation devrait faire partie de la Definition of Done :

## Definition of Done - Documentation

Une User Story est terminee du point de vue documentation quand :

- [ ] Toutes les nouvelles methodes publiques ont ABAP Doc
- [ ] Les parametres et exceptions sont documentes
- [ ] La logique metier complexe est commentee
- [ ] Le README est mis a jour (si pertinent)
- [ ] Les diagrammes d'architecture sont adaptes (si pertinent)

Template Pull Request

## Description
[Qu'est-ce qui a ete modifie ?]

## Documentation
- [ ] ABAP Doc pour les methodes nouvelles/modifiees
- [ ] README mis a jour
- [ ] Exemples ajoutes/mis a jour

## Checklist
- [ ] Le code compile
- [ ] Les tests passent
- [ ] **Documentation verifiee**

Automatisation avec ATC

" Custom ATC Check pour la documentation
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.

Resume des bonnes pratiques

A faire

Principe	Exemple
Connaitre le public cible	Debutants vs. Experts
Utiliser des exemples	Code concret
Maintenir a jour	Avec les modifications de code
Ecrire de maniere structuree	Hierarchie claire
Rester coherent	Formats uniformes

A eviter

Erreur	Mieux
”Auto-explicatif”	Documenter quand meme
Repeter le code	Expliquer l’objectif
Trop de details	Se concentrer sur l’essentiel
Jargon sans explication	Definir les termes
Ecrire une seule fois	Mettre a jour regulierement

Conclusion

Une bonne documentation technique est un investissement qui rapporte plusieurs fois. Dans l’environnement SAP, ou les systemes sont souvent en service pendant des decennies, une documentation comprehensible est indispensable.

Les points cles :

Differents types de documentation pour differents objectifs
Templates pour une qualite coherente
Documentation comme partie du code
Maintenance reguliere a planifier
Automatisation la ou c’est possible

Avec ces bases, vous pouvez creer une documentation que votre equipe et les futurs developpeurs apprecieront.

Sujets connexes

Clean ABAP - Un code propre comme base
Devenir developpeur ABAP Cloud - Parcours de carriere
abapGit - Versioning et documentation