Documentation & ADRs - Archyl Docs

Créez et gérez la documentation d'architecture et les Architecture Decision Records dans Archyl

Documentation & ADRs

Archyl fournit des fonctionnalités de documentation puissantes qui vous permettent de créer une documentation riche et liée aux côtés de vos diagrammes d'architecture. Gardez vos connaissances architecturales organisées et connectées.

Créer de la Documentation

Documentation Manuelle

Pour créer de la documentation manuellement :

  1. Allez dans l'onglet Docs de votre projet
  2. Cliquez sur Nouveau Doc
  3. Entrez un titre et écrivez votre contenu en Markdown
  4. Ajoutez des tags pour l'organisation
  5. Cliquez sur Enregistrer

La documentation supporte la syntaxe Markdown complète incluant :

  • Titres et formatage
  • Blocs de code avec coloration syntaxique
  • Tableaux et listes
  • Images et liens

Import depuis Git

Vous pouvez importer la documentation existante depuis votre dépôt Git :

  1. Allez dans Paramètres du Projet > Découverte de Documentation
  2. Configurez votre connexion au dépôt
  3. Cliquez sur Découvrir les Docs
  4. Révisez et approuvez la documentation découverte

C'est parfait pour importer des fichiers README existants, des spécifications techniques ou du contenu wiki.

Liaison aux Éléments d'Architecture

La documentation devient plus puissante quand elle est liée à votre architecture :

Créer des Liens

  1. Ouvrez une page de documentation
  2. Cliquez sur Lier à un Élément
  3. Recherchez ou parcourez l'élément d'architecture
  4. Sélectionnez le(s) élément(s) à lier
  5. Cliquez sur Terminé

Voir la Documentation Liée

Lors de la visualisation d'un élément dans le diagramme, la documentation liée apparaît dans le panneau de détails. Cela fournit un contexte instantané sans quitter la vue du diagramme.

Cas d'Utilisation pour la Liaison

  • Lier la documentation API aux conteneurs Service
  • Lier les guides d'installation aux composants d'infrastructure
  • Lier les spécifications de conception aux contextes système
  • Lier les commentaires de code aux éléments Code

Architecture Decision Records (ADRs)

Les ADRs documentent les décisions architecturales importantes avec leur contexte et leurs conséquences.

Qu'est-ce qu'un ADR ?

Un Architecture Decision Record capture :

Champ Description
Titre Ce qui a été décidé
Statut Proposé, Accepté, Déprécié, ou Remplacé
Contexte Pourquoi cette décision était nécessaire
Décision Ce qui a été décidé
Conséquences Impact de la décision

Créer un ADR

  1. Allez dans l'onglet Décisions de votre projet
  2. Cliquez sur Nouveau ADR
  3. Remplissez les champs de l'ADR
  4. Liez aux éléments d'architecture pertinents
  5. Cliquez sur Enregistrer

Workflow ADR

Les ADRs suivent un cycle de vie :

  1. Proposé : Brouillon initial, en discussion
  2. Accepté : La décision a été prise et approuvée
  3. Déprécié : Plus pertinent mais conservé pour l'historique
  4. Remplacé : Remplacé par une décision plus récente

Découverte d'ADR

Comme la documentation, les ADRs peuvent être découverts depuis votre dépôt :

  1. Allez dans Paramètres du Projet > Découverte ADR
  2. Configurez le chemin vers vos ADRs (ex : docs/adr/)
  3. Cliquez sur Découvrir les ADRs
  4. Révisez et approuvez les enregistrements découverts

Bonnes Pratiques

Gardez la Documentation à Jour

  • Mettez à jour les docs quand l'architecture change
  • Révisez la documentation pendant les rétrospectives de sprint
  • Utilisez les ADRs pour les décisions significatives

Liez Tout

  • Chaque système devrait avoir un doc de description
  • Liez les ADRs aux composants affectés
  • Faites des références croisées de la documentation liée

Utilisez les Tags Efficacement

  • Taggez par domaine (auth, paiements, etc.)
  • Taggez par type (api, guide, spec)
  • Taggez par statut (brouillon, révision, final)

Guidelines ADR

  • Créez des ADRs pour les décisions significatives
  • Incluez les alternatives considérées
  • Documentez les compromis
  • Liez aux PRs d'implémentation quand possible

Paramètres de Découverte de Documentation

Configurez comment la documentation est découverte :

Patterns de Chemin

Spécifiez quels chemins scanner :

docs/
wiki/
README.md
*.md

Patterns d'Exclusion

Ignorez certains fichiers :

node_modules/
vendor/
CHANGELOG.md

Prochaines Étapes