371 lines
13 KiB
Markdown
371 lines
13 KiB
Markdown
---
|
|
title: "Guide de style de la documentation"
|
|
description: Conventions de documentation spécifiques au projet, basées sur le style Google et la structure Diataxis
|
|
---
|
|
|
|
Ce projet suit le [Guide de style de documentation pour développeurs Google](https://developers.google.com/style) et utilise [Diataxis](https://diataxis.fr/) pour structurer le contenu. Seules les conventions spécifiques au projet sont présentées ci-dessous.
|
|
|
|
## Règles spécifiques au projet
|
|
|
|
| Règle | Spécification |
|
|
| --------------------------------------- | ------------------------------------------------------ |
|
|
| Pas de règles horizontales (`---`) | Perturbe le flux de lecture des fragments |
|
|
| Pas de titres `####` | Utiliser du texte en gras ou des admonitions |
|
|
| Pas de sections « Related » ou « Next: » | La barre latérale gère la navigation |
|
|
| Pas de listes profondément imbriquées | Diviser en sections à la place |
|
|
| Pas de blocs de code pour non-code | Utiliser des admonitions pour les exemples de dialogue |
|
|
| Pas de paragraphes en gras pour les appels | Utiliser des admonitions à la place |
|
|
| 1-2 admonitions max par section | Les tutoriels permettent 3-4 par section majeure |
|
|
| Cellules de tableau / éléments de liste | 1-2 phrases maximum |
|
|
| Budget de titres | 8-12 `##` par doc ; 2-3 `###` par section |
|
|
|
|
## Admonitions (Syntaxe Starlight)
|
|
|
|
```md
|
|
:::tip[Titre]
|
|
Raccourcis, bonnes pratiques
|
|
:::
|
|
|
|
:::note[Titre]
|
|
Contexte, définitions, exemples, prérequis
|
|
:::
|
|
|
|
:::caution[Titre]
|
|
Mises en garde, problèmes potentiels
|
|
:::
|
|
|
|
:::danger[Titre]
|
|
Avertissements critiques uniquement — perte de données, problèmes de sécurité
|
|
:::
|
|
```
|
|
|
|
### Utilisations standards
|
|
|
|
| Admonition | Usage |
|
|
| -------------------------- | ---------------------------------------- |
|
|
| `:::note[Pré-requis]` | Dépendances avant de commencer |
|
|
| `:::tip[Chemin rapide]` | Résumé TL;DR en haut du document |
|
|
| `:::caution[Important]` | Mises en garde critiques |
|
|
| `:::note[Exemple]` | Exemples de commandes/réponses |
|
|
|
|
## Formats de tableau standards
|
|
|
|
**Phases :**
|
|
|
|
```md
|
|
| Phase | Nom | Ce qui se passe |
|
|
| ----- | ---------- | --------------------------------------------------- |
|
|
| 1 | Analyse | Brainstorm, recherche *(optionnel)* |
|
|
| 2 | Planification | Exigences — PRD ou spécification technique *(requis)* |
|
|
```
|
|
|
|
**Skills :**
|
|
|
|
```md
|
|
| Skill | Agent | Objectif |
|
|
| ------------------- | ------- | ----------------------------------------------- |
|
|
| `bmad-brainstorming` | Analyste | Brainstorming pour un nouveau projet |
|
|
| `bmad-create-prd` | PM | Créer un document d'exigences produit |
|
|
```
|
|
|
|
## Blocs de structure de dossiers
|
|
|
|
À afficher dans les sections "Ce que vous avez accompli" :
|
|
|
|
````md
|
|
```
|
|
votre-projet/
|
|
├── _bmad/ # Configuration BMad
|
|
├── _bmad-output/
|
|
│ ├── planning-artifacts/
|
|
│ │ └── PRD.md # Votre document d'exigences
|
|
│ ├── implementation-artifacts/
|
|
│ └── project-context.md # Règles d'implémentation (optionnel)
|
|
└── ...
|
|
```
|
|
````
|
|
|
|
## Structure des tutoriels
|
|
|
|
```text
|
|
1. Titre + Accroche (1-2 phrases décrivant le résultat)
|
|
2. Notice de version/module (admonition info ou avertissement) (optionnel)
|
|
3. Ce que vous allez apprendre (liste à puces des résultats)
|
|
4. Prérequis (admonition info)
|
|
5. Chemin rapide (admonition tip - résumé TL;DR)
|
|
6. Comprendre [Sujet] (contexte avant les étapes - tableaux pour phases/agents)
|
|
7. Installation (optionnel)
|
|
8. Étape 1 : [Première tâche majeure]
|
|
9. Étape 2 : [Deuxième tâche majeure]
|
|
10. Étape 3 : [Troisième tâche majeure]
|
|
11. Ce que vous avez accompli (résumé + structure de dossiers)
|
|
12. Référence rapide (tableau des compétences)
|
|
13. Questions courantes (format FAQ)
|
|
14. Obtenir de l'aide (liens communautaires)
|
|
15. Points clés à retenir (admonition tip)
|
|
```
|
|
|
|
### Liste de vérification des tutoriels
|
|
|
|
- [ ] L'accroche décrit le résultat en 1-2 phrases
|
|
- [ ] Section "Ce que vous allez apprendre" présente
|
|
- [ ] Prérequis dans une admonition
|
|
- [ ] Admonition TL;DR de chemin rapide en haut
|
|
- [ ] Tableaux pour phases, skills, agents
|
|
- [ ] Section "Ce que vous avez accompli" présente
|
|
- [ ] Tableau de référence rapide présent
|
|
- [ ] Section questions courantes présente
|
|
- [ ] Section obtenir de l'aide présente
|
|
- [ ] Admonition points clés à retenir à la fin
|
|
|
|
## Structure des guides pratiques (How-To)
|
|
|
|
```text
|
|
1. Titre + Accroche (une phrase : « Utilisez le workflow `X` pour... »)
|
|
2. Quand utiliser ce guide (liste à puces de scénarios)
|
|
3. Quand éviter ce guide (optionnel)
|
|
4. Prérequis (admonition note)
|
|
5. Étapes (sous-sections ### numérotées)
|
|
6. Ce que vous obtenez (produits de sortie/artefacts)
|
|
7. Exemple (optionnel)
|
|
8. Conseils (optionnel)
|
|
9. Prochaines étapes (optionnel)
|
|
```
|
|
|
|
### Liste de vérification des guides pratiques
|
|
|
|
- [ ] L'accroche commence par « Utilisez le workflow `X` pour... »
|
|
- [ ] "Quand utiliser ce guide" contient 3-5 points
|
|
- [ ] Prérequis listés
|
|
- [ ] Les étapes sont des sous-sections `###` numérotées avec des verbes d'action
|
|
- [ ] "Ce que vous obtenez" décrit les artefacts produits
|
|
|
|
## Structure des explications
|
|
|
|
### Types
|
|
|
|
| Type | Exemple |
|
|
| ----------------------- | ------------------------------------ |
|
|
| **Index/Page d'accueil** | `core-concepts/index.md` |
|
|
| **Concept** | `what-are-agents.md` |
|
|
| **Fonctionnalité** | `quick-dev.md` |
|
|
| **Philosophie** | `why-solutioning-matters.md` |
|
|
| **FAQ** | `established-projects-faq.md` |
|
|
|
|
### Modèle général
|
|
|
|
```text
|
|
1. Titre + Accroche (1-2 phrases)
|
|
2. Vue d'ensemble/Définition (ce que c'est, pourquoi c'est important)
|
|
3. Concepts clés (sous-sections ###)
|
|
4. Tableau comparatif (optionnel)
|
|
5. Quand utiliser / Quand ne pas utiliser (optionnel)
|
|
6. Diagramme (optionnel - mermaid, 1 max par doc)
|
|
7. Prochaines étapes (optionnel)
|
|
```
|
|
|
|
### Pages d'index/d'accueil
|
|
|
|
```text
|
|
1. Titre + Accroche (une phrase)
|
|
2. Tableau de contenu (liens avec descriptions)
|
|
3. Pour commencer (liste numérotée)
|
|
4. Choisissez votre parcours (optionnel - arbre de décision)
|
|
```
|
|
|
|
### Explications de concepts
|
|
|
|
```text
|
|
1. Titre + Accroche (ce que c'est)
|
|
2. Types/Catégories (sous-sections ###) (optionnel)
|
|
3. Tableau des différences clés
|
|
4. Composants/Parties
|
|
5. Lequel devriez-vous utiliser ?
|
|
6. Création/Personnalisation (lien vers les guides pratiques)
|
|
```
|
|
|
|
### Explications de fonctionnalités
|
|
|
|
```text
|
|
1. Titre + Accroche (ce que cela fait)
|
|
2. Faits rapides (optionnel - "Idéal pour :", "Temps :")
|
|
3. Quand utiliser / Quand ne pas utiliser
|
|
4. Comment cela fonctionne (diagramme mermaid optionnel)
|
|
5. Avantages clés
|
|
6. Tableau comparatif (optionnel)
|
|
7. Quand évoluer/mettre à niveau (optionnel)
|
|
```
|
|
|
|
### Documents de philosophie/justification
|
|
|
|
```text
|
|
1. Titre + Accroche (le principe)
|
|
2. Le problème
|
|
3. La solution
|
|
4. Principes clés (sous-sections ###)
|
|
5. Avantages
|
|
6. Quand cela s'applique
|
|
```
|
|
|
|
### Liste de vérification des explications
|
|
|
|
- [ ] L'accroche énonce ce que le document explique
|
|
- [ ] Contenu dans des sections `##` parcourables
|
|
- [ ] Tableaux comparatifs pour 3+ options
|
|
- [ ] Les diagrammes ont des étiquettes claires
|
|
- [ ] Liens vers les guides pratiques pour les questions procédurales
|
|
- [ ] 2-3 admonitions max par document
|
|
|
|
## Structure des références
|
|
|
|
### Types
|
|
|
|
| Type | Exemple |
|
|
| ----------------------- | --------------------- |
|
|
| **Index/Page d'accueil** | `workflows/index.md` |
|
|
| **Catalogue** | `agents/index.md` |
|
|
| **Approfondissement** | `document-project.md` |
|
|
| **Configuration** | `core-tasks.md` |
|
|
| **Glossaire** | `glossary/index.md` |
|
|
| **Complet** | `bmgd-workflows.md` |
|
|
|
|
### Pages d'index de référence
|
|
|
|
```text
|
|
1. Titre + Accroche (une phrase)
|
|
2. Sections de contenu (## pour chaque catégorie)
|
|
- Liste à puces avec liens et descriptions
|
|
```
|
|
|
|
### Référence de catalogue
|
|
|
|
```text
|
|
1. Titre + Accroche
|
|
2. Éléments (## pour chaque élément)
|
|
- Brève description (une phrase)
|
|
- **Skills :** ou **Infos clés :** sous forme de liste simple
|
|
3. Universel/Partagé (## section) (optionnel)
|
|
```
|
|
|
|
### Référence d'approfondissement d'élément
|
|
|
|
```text
|
|
1. Titre + Accroche (objectif en une phrase)
|
|
2. Faits rapides (admonition note optionnelle)
|
|
- Module, Skill, Entrée, Sortie sous forme de liste
|
|
3. Objectif/Vue d'ensemble (## section)
|
|
4. Comment invoquer (bloc de code)
|
|
5. Sections clés (## pour chaque aspect)
|
|
- Utiliser ### pour les sous-options
|
|
6. Notes/Mises en garde (admonition tip ou caution)
|
|
```
|
|
|
|
### Référence de configuration
|
|
|
|
```text
|
|
1. Titre + Accroche
|
|
2. Table des matières (liens de saut si 4+ éléments)
|
|
3. Éléments (## pour chaque config/tâche)
|
|
- **Résumé en gras** — une phrase
|
|
- **Utilisez-le quand :** liste à puces
|
|
- **Comment cela fonctionne :** étapes numérotées (3-5 max)
|
|
- **Sortie :** résultat attendu (optionnel)
|
|
```
|
|
|
|
### Guide de référence complet
|
|
|
|
```text
|
|
1. Titre + Accroche
|
|
2. Vue d'ensemble (## section)
|
|
- Diagramme ou tableau montrant l'organisation
|
|
3. Sections majeures (## pour chaque phase/catégorie)
|
|
- Éléments (### pour chaque élément)
|
|
- Champs standardisés : Skill, Agent, Entrée, Sortie, Description
|
|
4. Prochaines étapes (optionnel)
|
|
```
|
|
|
|
### Liste de vérification des références
|
|
|
|
- [ ] L'accroche énonce ce que le document référence
|
|
- [ ] La structure correspond au type de référence
|
|
- [ ] Les éléments utilisent une structure cohérente
|
|
- [ ] Tableaux pour les données structurées/comparatives
|
|
- [ ] Liens vers les documents d'explication pour la profondeur conceptuelle
|
|
- [ ] 1-2 admonitions max
|
|
|
|
## Structure du glossaire
|
|
|
|
Starlight génère la navigation "Sur cette page" à droite à partir des titres :
|
|
|
|
- Catégories en tant que titres `##` — apparaissent dans la navigation à droite
|
|
- Termes dans des tableaux — lignes compactes, pas de titres individuels
|
|
- Pas de TOC en ligne — la barre latérale à droite gère la navigation
|
|
|
|
### Format de tableau
|
|
|
|
```md
|
|
## Nom de catégorie
|
|
|
|
| Terme | Définition |
|
|
| ------------ | --------------------------------------------------------------------------------------------- |
|
|
| **Agent** | Personnalité IA spécialisée avec une expertise spécifique qui guide les utilisateurs dans les workflows. |
|
|
| **Workflow** | Processus guidé en plusieurs étapes qui orchestre les activités des agents IA pour produire des livrables. |
|
|
```
|
|
|
|
### Règles de définition
|
|
|
|
| À faire | À ne pas faire |
|
|
| --------------------------------- | --------------------------------------------- |
|
|
| Commencer par ce que c'est ou ce que cela fait | Commencer par « C'est... » ou « Un [terme] est... » |
|
|
| Se limiter à 1-2 phrases | Écrire des explications de plusieurs paragraphes |
|
|
| Mettre le nom du terme en gras dans la cellule | Utiliser du texte simple pour les termes |
|
|
|
|
### Marqueurs de contexte
|
|
|
|
Ajouter un contexte en italique au début de la définition pour les termes à portée limitée :
|
|
|
|
- `*Quick Dev uniquement.*`
|
|
- `*méthode BMad/Enterprise.*`
|
|
- `*Phase N.*`
|
|
- `*BMGD.*`
|
|
- `*Projets établis.*`
|
|
|
|
### Liste de vérification du glossaire
|
|
|
|
- [ ] Termes dans des tableaux, pas de titres individuels
|
|
- [ ] Termes alphabétisés au sein des catégories
|
|
- [ ] Définitions de 1-2 phrases
|
|
- [ ] Marqueurs de contexte en italique
|
|
- [ ] Noms des termes en gras dans les cellules
|
|
- [ ] Pas de définitions « Un [terme] est... »
|
|
|
|
## Sections FAQ
|
|
|
|
```md
|
|
## Questions
|
|
|
|
- [Ai-je toujours besoin d'architecture ?](#ai-je-toujours-besoin-darchitecture)
|
|
- [Puis-je modifier mon plan plus tard ?](#puis-je-modifier-mon-plan-plus-tard)
|
|
|
|
### Ai-je toujours besoin d'architecture ?
|
|
|
|
Uniquement pour les parcours méthode BMad et Enterprise. Quick Dev passe directement à l'implémentation.
|
|
|
|
### Puis-je modifier mon plan plus tard ?
|
|
|
|
Oui. Utilisez `bmad-correct-course` pour gérer les changements de portée.
|
|
|
|
**Une question sans réponse ici ?** [Ouvrez une issue](...) ou posez votre question sur [Discord](...).
|
|
```
|
|
|
|
## Commandes de validation
|
|
|
|
Avant de soumettre des modifications de documentation :
|
|
|
|
```bash
|
|
npm run docs:fix-links # Prévisualiser les corrections de format de liens
|
|
npm run docs:fix-links -- --write # Appliquer les corrections
|
|
npm run docs:validate-links # Vérifier que les liens existent
|
|
npm run docs:build # Vérifier l'absence d'erreurs de build
|
|
```
|