Diagrammes de sirènes

Le diagramme de la sirène intègre directement la création de diagrammes natifs dans l’éditeur. Propulsé par Mermaid.js, il vous permet d’écrire une syntaxe de diagramme textuel et de voir un diagramme visuel rendu en temps réel – le tout sans quitter votre espace de documentation de documentation. Les diagrammes sont stockés sous forme de code source modifiable aux côtés d’une image rendue. Cela signifie que vos diagrammes sont toujours rééditables et ne deviennent jamais des captures d’écran statiques et répétées.

Qu’est-ce que Mermaid.js ?

Mermaid.js est une bibliothèque de diagrammes open source qui convertit la syntaxe du texte brut en diagrammes visuels. Au lieu de dessiner les formes manuellement dans un outil séparé, vous décrivez le diagramme en texte et la Sirène l’affiche. Document360 Mermaid.js’intègre directement dans l’éditeur, donc tout le flux de travail se déroule sans quitter votre article.

Exemple : Les quatre lignes de texte suivantes produisent un organigramme complet :

graph TD
  A[User submits ticket] --> B{Priority?}
  B -- High --> C[Notify on-call team]
  B -- Low  --> D[Add to backlog]

Quand utiliser les diagrammes de sirènes

Utilisez des diagrammes de sirène lorsque votre contenu implique un processus, une relation ou une structure plus difficile à expliquer uniquement avec des mots. Quelques scénarios courants :

• Un rédacteur technique documentant un processus d’approbation ou d’intégration
• Un développeur ou un architecte illustrant une interaction API, une architecture système ou un schéma de base de données
• Un chef de produit cartographiant un parcours utilisateur ou visualisant un calendrier de projet
• Une équipe de support qui construit un organigramme de dépannage ou un chemin d’escalade

Si vous vous retrouvez à décrire une séquence d’étapes ou de connexions entre des composants sur plusieurs paragraphes, un schéma communiquera presque toujours cela plus rapidement.

Principaux avantages

Insertion d’un diagramme de sirène

Pour insérer un diagramme de la sirène dans votre article :

1. Cliquez à l’intérieur du corps de l’article où vous souhaitez que le schéma apparaisse.
2. Tapez / (barre oblique avant) pour déclencher le menu de commande de barre.
3. Tapez Sirène pour filtrer les suggestions.
4. Sélectionnez le diagramme de la sirène dans le menu déroulant.

Choisir un modèle

Une fois que vous déclenchez l’insertion du diagramme de la sirène, le modal de sélection du modèle apparaît. C’est là que vous choisissez le point de départ pour votre diagramme.

• À partir d’un modèle — Parcourez ou recherchez les 23 modèles disponibles, puis cliquez sur l’un d’eux. L’éditeur s’ouvre avec la syntaxe de ce modèle préchargée.
• Depuis vide — Cliquez sur Vide pour ouvrir l’éditeur avec un panneau de syntaxe vide. Utilise-le uniquement si tu connais déjà la syntaxe des sirènes.

Choisir un modèle

1. Parcourez les 23 cartes modèles ou tapez un mot-clé (par exemple flow, sequence, gantt) dans la barre de recherche.
2. Cliquez sur la fiche modèle qui correspond à ce que vous souhaitez créer.
3. L’éditeur s’ouvre avec la syntaxe de ce modèle préchargée. Modifiez-le davantage pour qu’il corresponde à votre contenu.

Utilisation d’une toile vierge

1. Cliquez sur l’option Vide dans la grille du modèle.
2. L’éditeur s’ouvre sur un panneau de syntaxe vide.
3. Tape ta syntaxe de la sirène à partir de zéro.

Rédiger et prévisualiser votre schéma

L’éditeur de diagrammes de la sirène est un espace de travail à deux panneaux. Le panneau de gauche est l’endroit où vous écrivez la syntaxe de votre sirène. Le panneau de droite vous montre un aperçu en temps réel du diagramme pendant que vous tapez.

1. Commencez par une déclaration de type diagramme sur la première ligne. Cela indique à la Sirène quel type de diagramme rendre.

   Type de diagramme	Première ligne
   Organigramme (de haut en bas)	graph TD
   Organigramme (de gauche à droite)	graph LR
   Diagramme de séquence	sequenceDiagram
   Diagramme de classes	classDiagram
   Diagramme de Gantt	gantt
   Diagramme d’état	stateDiagram-v2
   Diagramme entité-relation	erDiagram
   Graphique circulaire	pie
   Carte mentale	mindmap

2. Ajoutez des nœuds, des connexions et des étiquettes sur les lignes suivantes. Chaque ligne que vous tapez met immédiatement à jour l’aperçu à droite.

3. Si vous travaillez à partir d’un modèle, il suffit de remplacer le texte provisoire par vos propres labels et connexions.

Si votre syntaxe comporte de très longues lignes (par exemple, de longues étiquettes de nœuds ou des descriptions détaillées des arêtes), cliquez sur le bouton Enrouler le code sous le panneau de syntaxe pour enrouler de longues lignes dans la largeur visible de l’éditeur. Cela n’affecte pas la sortie du diagramme — cela modifie seulement l’apparence du code dans l’éditeur.

Contrôles d’aperçu

Le panneau de droite se met à jour instantanément au fur et à mesure que vous écrivez. Utilisez les contrôles d’aperçu pour inspecter votre schéma avant de l’insérer.

Zoom in / Zoom out — Cliquez sur les boutons zoom in (+) ou zoom out (−) pour augmenter ou diminuer le grossissement de l’aperçu. Utilisez cela pour inspecter des parties spécifiques d’un diagramme complexe sans affecter la taille réelle du diagramme dans l’article.

Ajuster à l’écran — Cliquez sur l’icône d’ajuster à l’écran ( ) pour réinitialiser le niveau de zoom afin que tout le schéma soit visible dans la zone d’aperçu sans faire défiler. Utilisez ceci pour une dernière critique avant d’insérer.

Étendre / Réduire — Cliquez sur l’icône expand ( ) dans la barre d’outils du panneau d’aperçu pour masquer l’éditeur de syntaxe et élargir l’aperçu pour remplir toute la largeur modale. Cliquez sur l’icône de replier ( ) pour revenir à la vue en panneau partagé et continuer la modification.

Gestion des erreurs de syntaxe

Si votre syntaxe est invalide, l’aperçu affiche une erreur et le bouton Insérer est désactivé.

1. Lisez le message d’erreur. Il inclut le numéro de ligne qui cause le problème.
2. Corrigez cette ligne dans le panneau de syntaxe.
3. L’aperçu se met à jour automatiquement. Une fois valide, le bouton Insérer devient actif.

Erreurs courantes et corrections

:::(Attention) (

Insertion du diagramme dans l’article

Une fois que l’aperçu est correct et sans erreur, cliquez sur Insérer. Document360 convertit le diagramme en image SVG et le place à la position de votre curseur.

Deux éléments sont enregistrés pour chaque diagramme :

• L’image SVG rendue — visible dans l’article et sur le site de la base de données.
• La syntaxe de la Sirène — stockée en privé, utilisée lorsque vous modifierez le diagramme plus tard.

Gestion d’un schéma inséré

Cliquez sur n’importe quel schéma inséré pour ouvrir le menu des bulles.

Édition d’un diagramme existant

Chaque diagramme de la sirène que vous insérez peut être édité à tout moment, même après la publication de l’article. La syntaxe originale est toujours stockée.

1. Cliquez sur le diagramme, puis cliquez sur Modifier le diagramme dans le menu des bulles.
2. L’éditeur commence avec la syntaxe stockée et un aperçu en direct.
3. Fais tes changements.
4. Cliquez sur Mettre à jour. Le schéma de l’article est remplacé ; la position et l’alignement sont préservés.

Si vous cliquez sur Annuler ou (X) après avoir effectué des modifications, une boîte de confirmation apparaît. Cliquez sur Oui, défausser pour sortir sans sauvegarder, ou Non, revenir pour continuer l’édition.

Comment les lecteurs perçoivent vos diagrammes

Sur le site de la base de connaissances, les diagrammes apparaissent sous forme d’images SVG statiques intégrées dans l’article. Les lecteurs peuvent cliquer sur n’importe quel diagramme pour ouvrir une superposition plein écran, ce qui est utile pour les diagrammes grands ou complexes. Les contrôles d’édition et la syntaxe source ne sont jamais exposés aux lecteurs.

Meilleures pratiques

• Un schéma, une idée. Si un organigramme dépasse 15 à 20 nœuds, séparez-le en un diagramme d’ensemble et un diagramme de détails.
• Ajoutez toujours une légende. Utilisez l’option légende dans le menu des bulles pour étiqueter chaque diagramme. Cela aide les lecteurs à comprendre le contexte en un coup d’œil.
• Utilisez SVG pour un usage externe. SVG est infiniment évolutif sans perte de qualité. N’utilisez PNG que lorsque l’outil de destination ne prend pas en compte SVG.
• Copiez pour dupliquer, pas pour reconstruire. Utilisez l’action du menu Copier la bulle pour dupliquer un diagramme. Chaque copie possède une syntaxe indépendante — l’édition de l’une n’affecte pas l’autre. Coller un diagramme de sirène en dehors de Document360 (par exemple dans un autre outil) ne collera que l’image, pas la syntaxe source.

Modèles disponibles

Les modèles suivants sont disponibles dans l’écran de sélection de modèles. Cherchez par nom ou mot-clé pour trouver rapidement le bon.

FAQ