Docs

• 1: Diagrams-as-Code
• 1.1: Mermaid
• 1.2: PlantUML
• 2: Documentation Engineering
• 3: Enterprise Architecture Management
• 4: Docs-as-Code
• 4.1: Asciidoc
• 4.2: Markdown

1 - Diagrams-as-Code

1.1 - Mermaid

Introduction

Mermaid est une bibliothèque de diagrammes et de visualisation basée sur JavaScript, qui permet de créer des diagrammes et des organigrammes à l’aide de descriptions textuelles. Mermaid est fréquemment utilisé dans les documents Markdown (par exemple, sur GitHub, GitLab ou Confluence) pour représenter visuellement des relations complexes.

Avantages de Mermaid :

• Intégration simple dans les documents Markdown.
• Aucun outil externe nécessaire – les diagrammes sont rendus directement dans le navigateur.
• Prend en charge une grande variété de types de diagrammes.
• Idéal pour la documentation, les présentations et les spécifications techniques.

Types de diagrammes possibles

Organigramme (Flowchart)

Les organigrammes visualisent des processus ou des flux de travail. Ils sont composés de nœuds (étapes) et de connexions (flèches) représentant la séquence des étapes.

Exemple :

flowchart TD
  A[Début] --> B{Décision}
  B -->|Oui| C[Processus 1]
  B -->|Non| D[Processus 2]
  C --> E[Fin]
  D --> E

flowchart TD
  A[Début] --> B{Décision}
  B -->|Oui| C[Processus 1]
  B -->|Non| D[Processus 2]
  C --> E[Fin]
  D --> E

Explication :

• flowchart TD : Définit un organigramme de haut en bas.
• A[Début] : Un nœud avec l’étiquette “Début”.
• --> : Connexion entre les nœuds.
• |Oui| et |Non| : Étiquettes pour les connexions.

Diagramme de classes (Class Diagram)

Les diagrammes de classes montrent la structure des classes, leurs attributs, leurs méthodes et leurs relations entre elles.

Exemple :

classDiagram
class Animal {
  -nom: String
  +manger()
}
class Chien {
  +aboyer()
}
Animal <|-- Chien

classDiagram
class Animal {
  -nom: String
  +manger()
}
class Chien {
  +aboyer()
}
Animal <|-- Chien

Explication :

• classDiagram : Définit un diagramme de classes.
• Animal et Chien : Classes avec attributs (-nom) et méthodes (+manger()).
• <|-- : Relation d’héritage (Chien hérite d’Animal).

Diagramme de séquence (Sequence Diagram)

Les diagrammes de séquence visualisent les interactions entre des objets ou des acteurs dans un ordre chronologique.

Exemple :

sequenceDiagram
    Alice->>Bob: Bonjour !
    Bob-->>Alice: Bonjour en retour !

sequenceDiagram
    Alice->>Bob: Bonjour !
    Bob-->>Alice: Bonjour en retour !

Explication :

• sequenceDiagram : Définit un diagramme de séquence.
• Alice->>Bob : Message d’Alice à Bob.
• -->> : Réponse de Bob à Alice.

Diagramme Entité-Association (ER Diagram)

Les diagrammes ER montrent les relations entre les entités dans une base de données.

Exemple :

erDiagram
    CLIENT ||--o{ COMMANDE : places
    CLIENT {
        int id PK
        string nom
    }
    COMMANDE {
        int id PK
        date date
    }

erDiagram
    CLIENT ||--o{ COMMANDE : places
    CLIENT {
        int id PK
        string nom
    }
    COMMANDE {
        int id PK
        date date
    }

Explication :

• erDiagram : Définit un diagramme ER.
• CLIENT ||--o{ COMMANDE : Un client a plusieurs commandes.
• PK : Clé primaire.

Diagramme d’états (State Diagram)

Les diagrammes d’états montrent les états d’un système et les transitions entre ces états.

Exemple :

stateDiagram-v2
    s1 --> Arrêt
    Arrêt --> Marche: Allumer
    Marche --> Arrêt: Éteindre

stateDiagram-v2
    s1 --> Arrêt
    Arrêt --> Marche: Allumer
    Marche --> Arrêt: Éteindre

Explication :

• stateDiagram-v2 : Définit un diagramme d’états.
• [*] : État de départ.
• Arrêt --> Marche : Transition de “Arrêt” à “Marche” via “Allumer”.

Diagramme heuristique (Mindmap)

Les cartes heuristiques visualisent des idées ou des concepts hiérarchiques.

Exemple :

mindmap
  root((Sujet))
    Branche 1
      Sous-sujet 1
      Sous-sujet 2
    Branche 2
      Sous-sujet 3

mindmap
  root((Sujet))
    Branche 1
      Sous-sujet 1
      Sous-sujet 2
    Branche 2
      Sous-sujet 3

Explication :

• mindmap : Définit une carte heuristique.
• root((Sujet)) : Sujet central.
• Les indentations définissent la hiérarchie.

Diagramme d’exigences (Requirement Diagram)

Les diagrammes d’exigences montrent les exigences et leurs relations.

Exemple :

requirementDiagram
  requirement Exigence1 {
    id: 1
    text: "Le système doit être sécurisé."
  }
  element Système {
    type: "logiciel"
  }
  Système - satisfies -> Exigence1

requirementDiagram
  requirement Exigence1 {
    id: 1
    text: "Le système doit être sécurisé."
  }
  element Système {
    type: "logiciel"
  }
  Système - satisfies -> Exigence1

Explication :

• requirementDiagram : Définit un diagramme d’exigences.
• requirement : Définit une exigence.
• satisfies : Relation entre un élément et une exigence.

Diagramme de Gantt

Les diagrammes de Gantt visualisent les plans de projet et les calendriers.

Exemple :

gantt
    title Plan de projet
    dateFormat YYYY-MM-DD
    section Phase 1
        Tâche 1 :a1, 2024-01-01, 7d
        Tâche 2 :after a1, 3d

gantt
    title Plan de projet
    dateFormat YYYY-MM-DD
    section Phase 1
        Tâche 1 :a1, 2024-01-01, 7d
        Tâche 2 :after a1, 3d

Explication :

• gantt : Définit un diagramme de Gantt.
• dateFormat : Format des dates.
• Tâche 1 :a1, 2024-01-01, 7d : La tâche 1 dure 7 jours à partir du 1er janvier 2024.

Chronologie (Timeline)

Les chronologies montrent les événements dans un ordre chronologique.

Exemple :

timeline
    title Événements importants 2024 : Événement 1
    2025 : Événement 2

timeline
    title Événements importants 2024 : Événement 1
    2025 : Événement 2

Explication :

• timeline : Définit une chronologie.
• 2024 : Événement 1 : Événement en l’année 2024.

Informations complémentaires

Liens web

Mermaid Open-Source

1.2 - PlantUML

Introduction

PlantUML est un outil open-source qui permet de générer des diagrammes à partir de simples descriptions textuelles. Il prend en charge une grande variété de types de diagrammes, tant basés sur UML que non basés sur UML. PlantUML est particulièrement utile pour les développeurs, les architectes et les chefs de projet, car il simplifie la création et la maintenance des diagrammes et peut être intégré dans de nombreux environnements de développement.

Diagrammes possibles basés sur UML

Diagramme de séquence

Description : Un diagramme de séquence montre l’interaction entre des objets dans un ordre spécifique. Il est fréquemment utilisé pour visualiser le flux de messages entre les objets d’un système.

Exemple en PlantUML :

@startuml 
Alice -> Bob: Bonjour ! 
Bob --> Alice: Bonjour en retour ! 
@enduml

Explication :

• -> indique un message d’un objet vers un autre.
• --> indique une réponse.

Diagrammes d’activité

Description : Les diagrammes d’activité (également appelés organigrammes) montrent le déroulement des activités et des décisions dans un processus. Ils sont particulièrement utiles pour visualiser des processus métiers ou des algorithmes.

Exemple en PlantUML :

@startuml 
start 
:Activité 1; :Activité 2; 
if (Condition?) then (Oui)
 :Activité 3; 
else (Non)
 :Activité 4; 
endif 
stop 
@enduml

Explication :

• start et stop marquent le début et la fin du processus.
• if et else indiquent des décisions.

Diagramme de classes

Description : Les diagrammes de classes montrent la structure d’un système à travers des classes, leurs attributs, leurs méthodes et les relations entre les classes.

Exemple en PlantUML :

@startuml 
class  Voiture {   
                -marque: String 
                -modele: String +rouler() 
                }   
class  Conducteur {   
                -nom: String +conduire() 
                }   
Voiture "1" *-- "1" Conducteur 
@enduml

Explication :

• - indique des attributs privés, + indique des méthodes publiques.
• --> indique une association entre des classes.

Diagramme d’objets

Description : Les diagrammes d’objets montrent les instances de classes à un moment donné et leurs relations entre elles.

Exemple en PlantUML :

@startuml 
object Voiture1 {
                marque = "VW" 
                modele = "Golf" 
                }   
object Conducteur1 {
                nom = "Max" 
                }   
Voiture1 --> Conducteur1
@enduml

Explication :

• object définit une instance d’une classe.
• --> indique une relation entre des objets.

Diagramme d’états

Description : Les diagrammes d’états montrent les différents états d’un objet et les transitions entre ces états.

Exemple en PlantUML :

@startuml 
[*] --> Arret 
Arret --> Marche : allumer 
Marche --> Arret : eteindre 
@enduml

Explication :

• [*] indique l’état initial.
• --> indique une transition entre états.

Diagrammes possibles non basés sur UML

Visualisation de données JSON/YAML

Description : PlantUML peut visualiser des données JSON ou YAML pour mieux comprendre la structure et la hiérarchie des données.

Exemple en PlantUML :

@startjson 
{
    "nom": "Max", 
    "age": 30, 
    "adresse": { 
                "rue": "Rue Principale 1", 
                "ville": "Berlin" 
                } 
} 
@endjson

Explication :

• @startjson et @endjson encadrent le code JSON.

Diagramme Archimate

Description : Les diagrammes Archimate sont utilisés pour modéliser des architectures d’entreprise. Ils montrent les relations entre les processus métiers, les applications et les technologies.

Exemple en PlantUML :

@startuml 
archimate #Business "Business Process" as bp <<business-process>> 
archimate #Application "Application" as app <<application-component>>
bp --> app 
@enduml

Explication :

• archimate définit un élément Archimate.
• --> indique une relation entre des éléments.

Diagramme de Gantt

Description : Les diagrammes de Gantt montrent les plans de projet et le calendrier des tâches.

Exemple en PlantUML :

@startgantt 
[Tâche 1] lasts 5 days 
[Tâche 2] starts at [Tâche 1]'s end and lasts 3 days
@endgantt

Explication :

• lasts définit la durée d’une tâche.
• starts at indique le début d’une tâche par rapport à une autre.

Diagramme de carte mentale (Mindmap)

Description : Les cartes mentales visualisent des idées et des concepts dans une structure hiérarchique.

Exemple en PlantUML :

@startmindmap 
* Racine 
** Branche 1 
*** Feuille 1 
** Branche 2 
@endmindmap

Explication :

• * indique le nœud racine.
• ** et *** indiquent des nœuds enfants.

Diagramme de réseau

Description : Les diagrammes de réseau montrent la structure et les connexions dans un réseau.

Exemple en PlantUML :

@startuml 
node "Serveur" as s 
node "Client" as c 
s -- c 
@enduml

Explication :

• node définit un nœud dans le réseau.
• -- indique une connexion entre des nœuds.

Structure de découpage du projet (WBS)

Description : Une structure de découpage du projet (WBS) montre la hiérarchie et la structure d’un projet.

Exemple en PlantUML :

@startwbs 
* Projet 
** Phase 1 
*** Tâche 1 
*** Tâche 2 
** Phase 2 
@endwbs

Explication :

• * indique le projet principal.
• ** et *** indiquent des sous-éléments.

Informations complémentaires

Liens web

• PlantUML

2 - Documentation Engineering

Ingénierie de la documentation – Définition, objectif et classification

Qu’est-ce que l’ingénierie de la documentation ?

L’ingénierie de la documentation désigne une approche systématique et ingénieriale de la planification, de la création, de la structuration, de la maintenance et du développement continu de la documentation.

L’objectif n’est pas le document individuel, mais la documentation en tant que système concevable :
avec des structures claires, des dépendances définies, des rôles, des outils et des cycles de vie.

L’ingénierie de la documentation considère donc la documentation de manière similaire aux logiciels, aux architectures ou aux processus métier :
comme quelque chose qui doit être conçu, exploité et amélioré en continu.

À quoi sert l’ingénierie de la documentation ?

L’ingénierie de la documentation répond aux problèmes typiques de la documentation classique :

• La documentation est incomplète ou obsolète
• Le savoir est lié à des personnes ou dispersé dans de nombreux silos
• Les documents sont difficiles à trouver ou contradictoires
• Les modifications sont laborieuses et sujettes aux erreurs
• La documentation croît de manière incontrôlée avec l’organisation et le paysage systémique

Cette approche permet de :

• Garder une vue d’ensemble sur des sujets complexes
• Assurer la cohérence sur de nombreux contenus
• Atteindre la durabilité lors de changements organisationnels ou de personnel
• Adapter la documentation de manière évolutive à la taille et à la complexité de l’entreprise
• Utiliser la documentation comme un outil de travail plutôt que comme un simple archivage

Qu’est-ce qui distingue l’ingénierie de la documentation de la documentation classique ?

La documentation classique se concentre souvent sur :

• des documents individuels
• le contenu textuel
• une maintenance manuelle
• des formats statiques

L’ingénierie de la documentation, en revanche, se concentre sur :

• les structures plutôt que les textes individuels
• les interconnexions plutôt que les contenus isolés
• la réutilisabilité plutôt que la redondance
• les processus et les outils plutôt que la création ponctuelle

En bref :

La documentation classique répond à la question Que documente-t-on ?
L’ingénierie de la documentation répond à la question Comment la documentation est-elle conçue en tant que système ?

Principes centraux de l’ingénierie de la documentation

Même sans cadre défini, on peut identifier des principes fondamentaux typiques :

1. La structure avant le contenu

Avant de créer du contenu, on clarifie :

• quels types d’informations existent
• comment ils sont liés les uns aux autres
• à quel niveau de détail ils doivent être documentés

2. Séparation du contenu et de la présentation

Le contenu est maintenu indépendamment du support de sortie.
La présentation (web, PDF, wiki, présentation) est secondaire.

3. Modularité et réutilisabilité

Les informations sont préparées de manière à pouvoir être :

• utilisées à plusieurs reprises
• combinées selon le contexte
• maintenues de manière centralisée

4. Pensée cycle de vie

La documentation possède :

• un contexte de création
• une phase d’utilisation
• des raisons de modification
• une fin possible

L’ingénierie de la documentation prend explicitement en compte ce cycle de vie.

Comment mettre en œuvre l’ingénierie de la documentation ?

L’ingénierie de la documentation n’est pas un outil unique, mais une combinaison de :

• modèles de pensée
• principes structurels
• rôles
• processus
• outils

Selon le contexte, différentes approches de mise en œuvre sont utilisées.

Docs-as-Ecosystems (La documentation en tant qu’écosystème)

Le terme Docs-as-Ecosystems décrit la documentation comme un système interconnecté composé de :

• contenus
• métadonnées
• relations
• versions
• publics cibles

La documentation n’est ainsi pas comprise comme une collection de fichiers individuels, mais comme un paysage informationnel qui grandit avec l’entreprise.

Caractéristiques typiques :

• logique claire de navigation et de liaison
• plusieurs points d’entrée pour différents publics cibles
• couplage lâche plutôt que documents monolithiques

Docs-as-Code (La documentation en tant que code)

Docs-as-Code transfère les principes éprouvés du développement logiciel à la documentation :

• contrôle de version (par ex. Git)
• révisions et validations
• builds automatisés
• modifications traçables

Avantages :

• transparence des modifications
• meilleure collaboration
• moindre dépendance envers des individus spécifiques
• meilleure intégration dans les processus de développement existants

Docs-as-Code n’est pas une fin en soi, mais un catalyseur pour une documentation durable.

Diagrams-as-Code (Les diagrammes en tant que code)

Diagrams-as-Code étend cette approche aux contenus graphiques :

• les diagrammes sont décrits textuellement
• ils sont versionnables
• ils peuvent être générés automatiquement

Exemples :

• diagrammes d’architecture
• représentations de processus
• vues d’ensemble des dépendances

L’avantage ne réside pas principalement dans la technique, mais dans :

• la cohérence entre texte et graphiques
• une meilleure maintenabilité
• une moindre rupture de support

Rôles et responsabilités

L’ingénierie de la documentation nécessite des responsabilités claires, par exemple :

• responsabilité du contenu (Qu’est-ce qui est correct ?)
• responsabilité structurelle (Où quelque chose appartient-il ?)
• responsabilité technique (Comment est-ce généré ?)

Ces rôles ne doivent pas nécessairement être des postes à temps plein, mais ils doivent être clairement désignés.

Quand l’ingénierie de la documentation est-elle utile ?

Cette approche est particulièrement pertinente lorsque :

• les organisations grandissent ou évoluent
• les systèmes et processus deviennent plus complexes
• le savoir ne peut plus être transmis de manière informelle
• la documentation acquiert une importance stratégique
• les exigences réglementaires ou organisationnelles augmentent

Pour des environnements très petits et stables, la documentation classique peut suffire.
Cependant, avec l’augmentation de la complexité, l’utilité d’une approche systématique croît considérablement.

Conclusion

L’ingénierie de la documentation n’est pas un nouveau mot à la mode, mais l’application cohérente d’une pensée ingénieriale à la documentation.

Elle permet de :

• rendre la documentation planifiable
• maîtriser la complexité
• maintenir le savoir disponible de manière durable

Non pas grâce à plus de documents, mais grâce à une meilleure structure, des responsabilités claires et des outils adaptés.

Une bonne documentation ne naît pas du hasard –
elle est le résultat d’une conception consciente.

Informations complémentaires

Littérature

• Docs Like Code (en anglais)

• Docs-as-Ecosystem (en anglais)

Liens web

• Documentation as Code (en anglais)

• What is Engineering Documentation? (en anglais)

• Documentation Engineering for Beginners (en anglais)

3 - Enterprise Architecture Management

La Gestion de l’Architecture d’Entreprise (EAM) est un outil de management stratégique qui aide les organisations à aligner leur infrastructure informatique sur leurs processus métier. Elle crée une transparence sur l’architecture de l’organisation et permet une évolution ciblée des modèles d’affaires, des applications et des technologies.

Niveaux

Niveau Métier

Le niveau métier décrit les objectifs stratégiques, les processus métier, les unités organisationnelles et les rôles de l’entreprise. Il constitue la base de tous les autres niveaux.

• Objectifs : Alignement stratégique, création de valeur, bénéfice client
• Processus : Processus métier de bout en bout (par ex. traitement des commandes, service client)
• Organisation : Structure, rôles, responsabilités
• Informations : Données métier, indicateurs clés, réglementations

Exemple : Une activité bancaire décrit les processus « soumission d’une demande de prêt », « vérification de la solvabilité », « conclusion du contrat ».

Niveau Application

Le niveau application décrit les systèmes logiciels et les applications utilisés pour soutenir les processus métier.

• Applications : Systèmes ERP, outils CRM, portails, microservices
• Intégrations : Interfaces entre les systèmes (API, middleware)
• Flux de données : Comment les données sont échangées entre les applications
• Dépendances fonctionnelles : Quelle application soutient quels processus métier

Exemple : SAP ERP soutient la comptabilité, Salesforce CRM soutient les ventes.

Niveau Technologie

Le niveau technologie décrit l’infrastructure informatique sur laquelle les applications s’exécutent.

• Matériel : Serveurs, centres de données, équipements utilisateurs
• Logiciels : Systèmes d’exploitation, bases de données, middleware
• Réseaux : LAN, WAN, infrastructure cloud
• Sécurité et Conformité : Contrôle d’accès, chiffrement, sauvegarde

Exemple : Environnement virtualisé avec Kubernetes, base de données PostgreSQL, hébergement cloud Azure.

Cadres de référence (Frameworks)

TOGAF (The Open Group Architecture Framework)

TOGAF est le cadre EAM le plus utilisé au monde. Il offre une approche structurée pour le développement et la gestion des architectures d’entreprise.

• ADM (Architecture Development Method) : Processus en 8 phases pour le développement de l’architecture
• Content Framework : Modèles pour les artefacts d’architecture (par ex. vues, modèles)
• Enterprise Continuum : Classification des architectures (du générique au spécifique)
• Standard TOGAF : Ouvert, extensible, maintenu par The Open Group

Avantages : Large acceptation, bien documenté, évolutif
Inconvénients : Complexe, effort d’apprentissage élevé

Cadre Zachman

Le Cadre Zachman est un schéma de classification qui structure les informations d’architecture selon deux dimensions : les Perspectives (Qui ? – du PDG au technicien) et les Aspects (Quoi ? Où ? Comment ? Quand ? Pourquoi ?).

• 6 Perspectives : Planificateur, Propriétaire, Concepteur, Constructeur, Sous-traitant, Entreprise
• 6 Aspects : Données, Fonction, Réseau, Personnes, Temps, Motivation
• Matrice 6x6 : Chaque cellule contient un artefact d’architecture spécifique

Avantages : Très structuré, idéal pour la documentation et la couverture
Inconvénients : Pas de processus, pas d’aide à l’implémentation

DYNAMAP (Dynamic Architecture Management)

DYNAMAP est un cadre EAM moderne et agile, conçu spécifiquement pour la transformation numérique et les organisations dynamiques.

• Accent sur l’agilité : Adaptation rapide aux changements du marché et de la technologie
• Architecture pilotée par les modèles : Utilisation de modèles pour l’automatisation et la simulation
• Capacité d’intégration : Relie l’EAM au DevOps, au cloud et à l’IA
• Orientation valeur : Met l’accent sur la valeur métier de chaque composant d’architecture

Avantages : Flexible, orienté numérique, adapté aux stratégies cloud et plateforme
Inconvénients : Moins établi, moins de standardisation

Informations complémentaires

Littérature

• Togaf, Archimate, UML et BPMN

Liens web

• TOGAF-Standard Website (en anglais)

• Zachmann International - About the Framework (en anglais)

• Enterprise Architecture Wheel (en anglais)

• Dynamap SI Framework d’architecture d’entreprise

Outils pour la mise en œuvre de l’EAM

Il y a nombreux logiciels disponibles sur le marché permettent de gérer des architectures. Je me concentres prinicpalement sur les solutions gratuites et open source, faciles à télécharger et à utiliser:

• Archi - archimate modelling

• Modelio Open Source

4 - Docs-as-Code

4.1 - Asciidoc

Syntax

Étant donné qu’AsciiDoc est proposé comme un « système complet », incluant langage et interpréteur, il existe une syntaxe centrale. Contrairement à Markdown, AsciiDoc ne connaît ni variantes ni dialectes.

Commentaires

Le code AsciiDoc peut être commenté, comme tout autre code source. Cela signifie que les commentaires ne sont pas pris en compte lors de l’interprétation du texte source (par exemple, lors de la conversion en PDF). Cela permet d’ajouter des commentaires à des documents ou à des parties de texte, ou de laisser des notes.

Ceci est un texte quelconque en AsciiDoc.

// Cette ligne ne sera pas interprétée.

Cette ligne sera affichée.

Paragraphes et sauts de ligne

AsciiDoc ne nécessite aucune indication spéciale pour les sauts de ligne et les paragraphes. Le texte est rendu tel qu’il a été écrit. Il est toutefois possible de forcer un saut de ligne à l’aide du symbole plus (+). Alternativement, l’attribut [%hardbreaks] peut être ajouté en préambule.

Ceci est la ligne numéro un.
Ceci est la ligne numéro deux.

Et maintenant un autre paragraphe.

Cette ligne sera +
sautée de force.

[%hardbreaks]
Ces lignes seront 
affichées telles quelles.

Mise en forme du texte

Gras, italique, mise en évidence, code

Pour mettre un texte en gras, en italique ou en code, il existe deux possibilités, selon que le texte à formater est isolé ou situé au milieu d’une phrase.

Un mot isolé peut être entouré d’astérisques, de tirets bas, de dièses ou d’accents graves simples.

Ce texte est *gras*.
Ce texte est _italique_.
Ce texte est `code`.
Ce texte est #mis en évidence#.

Si l’on souhaite formater une partie de texte au milieu d’une phrase, cela se fait en utilisant des astérisques, des tirets bas, des dièses ou des accents graves doubles. Si l’on tentait de le faire avec des caractères simples, la règle de formatage serait ignorée.

Les "tt" dans Mi**tt**ag sont en gras.
Les "tt" dans Mi*tt*ag ne sont pas en gras.

Les "tt" dans Mi__tt__ag sont en italique.
Les "tt" dans Mi_tt_ag ne sont pas en italique.

Les "tt" dans Mi``tt``ag sont du code.
Les "tt" dans Mi`tt`ag ne sont pas du code.

Les "tt" dans Mi##tt##ag sont mis en évidence.
Les "tt" dans Mi#tt#ag ne sont pas mis en évidence.

Souligné, barré

Pour souligner ou barrer un texte, on utilise des dièses accompagnés d’un attribut.

Ce texte est [.underline]#souligné#.
Ce texte est [.line-through]#barré#.

Exposant, indice et guillemets intelligents

Grâce aux commandes superscript et subscript, des parties de texte peuvent être mises en exposant ou en indice. Pour cela, le texte est placé entre un accent circonflexe (exposant) ou un tilde (indice).

Ceci est un ~bas~point.
Ceci est un ^haut^point.

Voici le texte AsciiDoc complété avec du contenu pour les chapitres vides (à partir de « Liens »), basé sur la syntaxe officielle AsciiDoc et les bonnes pratiques courantes :

Voici la version révisée de votre documentation AsciiDoc — désormais avec une explication courte et concise pour chaque chapitre, avant les exemples de syntaxe. Le tout reste clair, compréhensible et utile pour les débutants.

Liens

Explication :
AsciiDoc prend en charge à la fois les liens web externes, les renvois internes au document (ancres) et les liens vers des fichiers locaux. La syntaxe est simple et intuitive, idéale pour les documentations devant contenir des liens.

Liens externes

https://www.asciidoc.org[Site web AsciiDoc]

Liens internes (ancres)

[[section1]]
== Première section

Voir aussi <<section1>>.

Liens vers des fichiers

link:manuel.pdf[Télécharger le manuel]

En-tête du document

Explication :
L’en-tête du document contient des métadonnées telles que le titre, l’auteur, la date et des attributs globaux. Il est optionnel, mais recommandé pour les documents structurés, en particulier pour les exports PDF ou livres.

= Titre du document
Nom de l'auteur <auteur@exemple.com>
:doctype: book
:author: Nom de l'auteur
:revdate: 2026-02-09

Table des matières automatique

Explication :
Une table des matières (TOC) est générée automatiquement dès que l’attribut :toc: est défini. Elle peut être placée à gauche, à droite ou à n’importe quel endroit, ce qui est utile pour les documents longs.

:toc: left

= Titre principal

== Chapitre 1
Contenu...

== Chapitre 2
Autre contenu...

Inclusions

Explication :
Avec include::, vous pouvez intégrer des fichiers AsciiDoc externes ou des parties de ceux-ci. Pratique pour les sections réutilisables (pieds de page, notes, chapitres, etc.).

include::chapitre1.adoc[]

include::../partage/notes.adoc[tag=section2]

Listes

Explication :
AsciiDoc prend en charge les listes à puces (*), les listes numérotées (.) et les listes de définitions (::). L’indentation détermine la hiérarchie, ce qui assure une structure simple et claire.

Listes à puces

* Point 1
* Point 2
  * Sous-point

Listes numérotées

. Premier point
. Deuxième point
.. Sous-point

Listes de définitions

Terme::
  Définition du terme.

Images

Explication :
Les images sont intégrées avec image::. Vous pouvez contrôler la taille, le texte alternatif et la mise à l’échelle. Fonctionne en HTML, PDF et EPUB selon le moteur de rendu.

image::logo.png[Logo, 200, 100]

image::diagramme.svg[Diagramme, scaledwidth=50%]

Audio

Explication :
Les fichiers audio (par exemple, des messages vocaux) peuvent être intégrés directement dans le document. Utile pour les tutoriels ou les documentations multimédias.

audio::message-vocal.mp3[Message vocal, autoplay]

Vidéos

Explication :
Les vidéos sont intégrées avec video::. Vous pouvez activer des contrôles comme autoplay, controls ou loop, idéal pour les tutoriels ou présentations.

video::tutoriel.mp4[Tutoriel, width=640, height=360, autoplay, controls]

Macros pour clavier, boutons et menus

Explication :
Avec kbd: et menu:, vous pouvez mettre en évidence les raccourcis clavier et les chemins de menu, particulièrement utile dans les tutoriels ou la documentation logicielle.

Raccourcis clavier

Appuyez sur kbd:[Ctrl+C] pour copier.

Commandes de menu

Allez dans menu:Fichier[Enregistrer sous...].

Code source

Explication :
Les blocs de code avec coloration syntaxique sont introduits avec [source]. Vous pouvez spécifier des langages comme Python, Bash ou HTML, ce qui est utile pour la documentation destinée aux développeurs.

[source,python]
----
def bonjour():
    print("Bonjour le monde")
----

Notes et blocs de texte

Explication :
Avec NOTE:, TIP:, WARNING:, etc., vous pouvez mettre en évidence des informations importantes. Les citations avec ____ sont idéales pour citer des textes ou des sources externes.

Notes

NOTE: Ceci est une information importante.

TIP: Voici comment faire plus rapidement.

Citations

____
« Ceci est une citation. »
— Auteur
____

Tableaux

Explication :
Les tableaux sont définis avec |===. Chaque cellule est séparée par |. Vous pouvez contrôler le nombre de colonnes, les bordures et les en-têtes, parfait pour les comparaisons ou les données.

|===
| Colonne 1 | Colonne 2
| Valeur A  | Valeur B
| Valeur C  | Valeur D
|===

IDs, rôles et options

Explication :
Avec [[id]], vous définissez des ancres pour les liens internes. Avec [.rôle], vous pouvez attribuer des classes CSS. Avec [%option], vous contrôlez le comportement des blocs (par exemple, non numéroté).

IDs

[[chapitre2]]
== Chapitre 2

Rôles

[.note]
Ce texte a un rôle.

Options

[%unnumbered]
== Cette section n'a pas de numéro.

Attributs et caractères spéciaux

Explication :
Les attributs (:nom: valeur) permettent la réutilisation de texte ou de valeurs. Les caractères spéciaux comme + ou \\ doivent parfois être échappés pour ne pas être interprétés comme du formatage.

Attributs

:version: 1.0

La version est {version}.

Caractères spéciaux

+ pour plus, \\ pour barre oblique inverse, ' pour apostrophe.

Bibliographie

Explication :
Une bibliographie peut être créée manuellement ou via bibliography::. Utile pour les documents scientifiques ou référencés.

[bibliography]
== Littérature

- Auteur, Titre, Éditeur, Année

Notes de bas de page

Explication :
Les notes de bas de page sont insérées avec footnote:[Texte] ou [footnote:]. Elles apparaissent à la fin du document ou de la page, idéales pour des informations complémentaires.

Ceci est une phrase avec une note de bas de page.footnote:[Ceci est la note.]

Une autre phrase avec [footnote:2]Note 2[footnote:2].

Conclusion

Avantages

Un grand avantage d’AsciiDoc est certainement son large éventail de fonctionnalités, permettant même la création de documents complexes avec tables des matières et bibliographies. La fonction d’inclusion et la possibilité d’ajouter des commentaires facilitent la gestion de textes longs et de nombreux fichiers ; la collaboration en est également simplifiée. AsciiDoc n’étant pas seulement un langage, mais étant également livré avec une application, il est possible de travailler productivement sans détours inutiles. À part un éditeur de texte pour les fichiers, rien d’autre n’est nécessaire.

Inconvénients

AsciiDoc est loin d’être aussi répandu que Markdown. Des outils productifs comme des applications de notes, des wikis ou des générateurs de sites statiques prennent rarement en charge AsciiDoc, et quand c’est le cas, c’est généralement via des plugins. Ceux qui travaillent beaucoup avec de tels outils ne pourront pas éviter d’utiliser simultanément Markdown et AsciiDoc.

Pour aller plus loin

Littérature

• AsciiDoc for Beginners (en anglais)

Liens web

• AsciiDoc (en anglais)

• AsciiDoctor (en anglais)

Outils pour utiliser AsciiDoc

Éditeurs de texte

• AsciiDocFX

Générateurs de sites statiques

• Antora

Outils de transformation

• Pandoc

4.2 - Markdown

Markdown est certainement le langage de balisage simple le plus répandu.

Syntaxe

Syntaxe de base

Il s’agit des commandes de base que propose Markdown et qui devraient fondamentalement fonctionner dans tous les outils.

Titres

Pour afficher des titres, un ou plusieurs dièses sont placés devant le titre du niveau correspondant.

# Titre 1

## Titre 2

### Titre 3

#### Titre 4

##### Titre 5

###### Titre 6

Remarque : Il est préférable de toujours insérer une ligne vide avant un titre, car sinon les interprétations peuvent être incorrectes.

Paragraphes/Lignes

Il n’existe pas de réelles notations pour les sauts de ligne et les paragraphes ; le texte est affiché tel qu’écrit. Pour favoriser un saut de ligne, deux espaces peuvent être ajoutés à la fin de la ligne, ou alternativement, la balise HTML <br> peut être utilisée.

Première ligne avec deux espaces à la fin.  
Et maintenant la ligne suivante.

Première ligne avec la balise HTML à la fin.<br>
Et maintenant la ligne suivante.

Mise en forme du texte

Par défaut, Markdown offre la possibilité d’afficher le texte en gras et/ou en italique.

Pour afficher un texte en gras, la partie de texte correspondante est écrite entre deux étoiles ou deux underscores.

J'ai aussi du **texte en gras**.

J'ai aussi du __texte en gras__.

Et voici du **texte en gras** au milieu.

Pour afficher un texte en italique, la partie de texte correspondante est écrite entre une étoile ou un underscore.

J'ai aussi du *texte en italique*.

J'ai aussi du _texte en italique_.

Et voici du *texte en italique* au milieu.

Bien sûr, il est aussi possible de les combiner :

Pour afficher un texte en gras et en italique, la partie de texte correspondante est écrite entre trois étoiles ou trois underscores.

J'ai aussi du ***texte en gras et en italique***.

J'ai aussi du ___texte en gras et en italique___.

Et voici du ***texte en gras et en italique*** au milieu.

Citations (Blockquotes)

Pour citer un texte sous forme de bloc, il suffit de placer un signe « supérieur à » devant la ligne.

> Ce texte se trouve dans une citation.

Si la citation doit s’étendre sur plusieurs lignes, le signe « supérieur à » doit être placé au début de chaque ligne (y compris les lignes vides).

> Ce texte représente la première ligne de la citation.
> 
> Et voici la ligne suivante.

Les citations peuvent également être imbriquées ; dans ce cas, un signe « supérieur à » supplémentaire est ajouté pour le niveau ou l’indentation suivante.

> Ce texte se trouve dans une citation.
> 
>> Ce texte est imbriqué.

Listes

Les listes sont tout aussi simples et sont écrites directement dans le texte. Si la liste passe à un autre niveau, cela est permis par une indentation (4 espaces ou 1 tabulation).

Liste ordonnée

Les listes ordonnées sont générées en plaçant simplement le numéro correspondant suivi d’un point devant la ligne.

1. Premier élément
2. Deuxième élément
3. Troisième élément
    1. première indentation
    2. deuxième indentation
4. Quatrième élément

Liste non ordonnée

Les listes non ordonnées sont générées en plaçant simplement un tiret devant la ligne.

- Premier élément
- Deuxième élément
- Troisième élément
    - première indentation
    - deuxième indentation
- Quatrième élément

Liens et images

Pour afficher un lien, le texte du lien est placé entre crochets, suivi de l’URL entre parenthèses.

Les listes ordonnées sont générées en plaçant simplement le numéro correspondant suivi d’un point devant la ligne.

Mon moteur de recherche préféré est [Swisscows](https://swisscows.com/fr).

Un titre peut également être ajouté au lien sous forme d’infobulle.

Mon moteur de recherche préféré est [Swisscows](https://swisscows.com/fr "Le moteur de recherche suisse").

Comme forme abrégée, une URL peut aussi simplement être écrite entre crochets angulaires.

Mon moteur de recherche préféré est <https://swisscows.com/fr>.

Syntaxe étendue

Tableaux

Les tableaux sont définis à l’aide de barres verticales (|) et de tirets (-). La première ligne contient les en-têtes de colonnes, la deuxième ligne définit l’alignement (facultatif).

| Aligné à gauche | Centré        | Aligné à droite |
| :-------------- | :-----------: | --------------: |
| Cellule 1       | Cellule 2     | Cellule 3       |
| Cellule 4       | Cellule 5     | Cellule 6       |

Remarque : Le nombre de tirets dans la ligne de séparation est arbitraire ; seul le : pour l’alignement est important.

Blocs de code

Pour du code sur plusieurs lignes, un bloc de code est créé avec trois accents graves (```) ou avec quatre espaces par ligne. Facultativement, le langage peut être spécifié pour activer la coloration syntaxique.

```python
def hello():
    print("Bonjour le monde !")

---

#### Notes de bas de page

Les notes de bas de page sont insérées dans le texte avec `[^identifiant]` et définies à la fin du fichier avec `[^identifiant]:`.

```markdown
Voici un texte avec une note de bas de page.[^1]

[^1]: Ceci est l'explication de la note de bas de page.

Remarque : Tous les analyseurs Markdown ne prennent pas en charge les notes de bas de page – par exemple, Hugo nécessite goldmark avec l’option activée.

ID pour les titres

Les titres peuvent être dotés d’un ID pour y accéder directement (par exemple, pour les tables des matières ou les liens d’ancrage).

## Titre avec ID {#mon-id}

[Lien vers le titre](#mon-id)

Remarque : Dans Hugo, enableInlineShortcodes = true doit être activé dans la configuration.

Listes de tâches

Les listes de tâches (checklists) sont créées avec - [ ] pour les éléments non cochés et - [x] pour les éléments cochés.

- [x] Tâche terminée
- [ ] À faire
- [ ] À faire plus tard

Remarque : Souvent utilisé dans GitHub, GitLab ou des applications de notes comme Obsidian.

Texte barré

Le texte barré est entouré de deux tildes (~~).

Ce texte est ~~barré~~.

Émojis

Les émojis peuvent être insérés directement (par exemple, 😊) ou avec des codes courts comme :smile: (selon l’analyseur).

Je suis de bonne humeur aujourd'hui 😊

Remarque : Dans Hugo, les émojis doivent être explicitement activés (enableEmoji = true).

Mise en évidence du texte

Certains analyseurs (par exemple, Hugo avec Goldmark) prennent en charge la mise en évidence avec == :

Ce texte est ==mis en évidence==.

Remarque : Non standardisé – ne fonctionne pas partout.

Indices/Exposants

Les indices (H₂O) et les exposants (x²) sont représentés respectivement avec ~ et ^ – mais uniquement dans certaines extensions comme Pandoc ou Hugo avec un analyseur spécial.

L'eau est H~2~O.  
x^2^ est x au carré.

Remarque : Ne fait pas partie de la norme CommonMark – Fonctionne, par exemple, dans Hugo avec goldmark et l’option activée.

Utilisation

Markdown ne représente pas un système en soi, mais se contente d’une syntaxe ouverte et librement disponible. On pourrait comparer Markdown à un langage de script intégrable. C’est certainement aussi la raison pour laquelle tant de systèmes prennent en charge Markdown et que le langage est ainsi si polyvalent.

Systèmes Wiki

Les systèmes Wiki tels que Mediawiki (sur lequel Wikipédia est basé), dokuWiki, ou les fonctions wiki intégrées comme celles de GitHub ou GitLab utilisent standardement Markdown pour la gestion du contenu.

Les wikis sont avant tout là pour présenter du contenu, dans le domaine Git, la documentation du logiciel proposé. Grâce à la syntaxe simple, ceux-ci peuvent également être créés et gérés par des non-spécialistes.

Notes

Les applications de notes largement disponibles (ou parfois aussi appelées wikis de bureau) reposent également sur Markdown pour la gestion du contenu. Souvent, un éditeur WYSIWYG intégré est fourni, mais il utilise Markdown en arrière-plan. Il est également généralement possible de passer au texte source et d’éditer directement. Des exemples incluent Zim, Zettlr, QOwnNotes, et Logseq dans le domaine open source, ou des variantes populaires comme Evernote, Obsidian, ou Joplin.

Sites Web

Dans le domaine des sites Web, Markdown apparaît de deux manières. D’une part, les systèmes de gestion de contenu connus (comme WordPress et Drupal) offrent souvent des plugins/modules pour publier du contenu en Markdown. Mais outre les CMS, il existe aussi des SSG, appelés générateurs de sites statiques, comme Hugo ou Jekyll. De plus, il existe des systèmes similaires spécialisés dans la documentation technique comme MKDocs, Sphinx, ou Docusaurus. Ici aussi, tout le contenu est créé en Markdown puis converti en sites web statiques à l’aide d’un préprocesseur, qui peuvent ensuite être publiés.

Présentations/Cours

Outre les sites web, des présentations peuvent également être créées avec Markdown. Cependant, il ne s’agit pas de présentations PowerPoint, mais celles-ci sont dynamiquement converties en éléments web à l’aide de préprocesseurs. Des exemples incluent Marp, remarkJS, ou Cleaver. Spécifiquement pour les cours en ligne, l’extension Markdown LiaScript est appropriée.

Documents

Il manque certainement à Markdown certaines fonctionnalités qu’un traitement de texte comme MS Word ou LibreOffice Writer peut offrir, mais il est parfaitement suffisant pour des documents simples tels que des lettres.

Conclusion

Avantages

Markdown a une syntaxe simple et claire et est donc facile à apprendre. Les documents Markdown ont également l’avantage d’être facilement lisibles même en texte source. Ils sont donc à la fois lisibles par machine et par l’homme. Ce dernier grâce à la syntaxe simple et directe sans surcharge. La large diffusion de Markdown et son intégration dans tant d’outils parlent également d’eux-mêmes.

Inconvénients

Outre les avantages clairs, il y a malheureusement aussi des aspects négatifs à signaler concernant Markdown.

Markdown convient très bien pour des articles et des notes qui ne sont pas structurés de manière trop complexe. Si l’on souhaite créer davantage, par exemple des documents grands et complexes, tels que des livres entiers, des fonctions utiles comme une table des matières ou la possibilité d’imbriquer des fichiers en utilisant “Include” manquent.

Bien qu’il existe une norme Markdown avec CommonMark, la forte diffusion a néanmoins conduit à de nombreux “dialectes”, car de nombreux outils étendent la syntaxe standard avec leurs propres commandes. Par conséquent, les documents Markdown provenant de différents systèmes ne sont pas nécessairement compatibles entre eux.

Informations complémentaires

Liens Web

• CommonMark, der Markdown-Standard (en anglais)

• Markdown Guide (en anglais)

Outils pour utiliser Markdown

Wikis de bureau

• ZIM-Wiki

• Zettlr

• QOwnNotes

• Logseq

Éditeurs de texte

Générateurs de sites statiques

• Hugo

• MkDocs

• Sphinx

Outils de transformation

• Pandoc