veza/veza-docs/docs/meta/style-guide/index.mdx

---
id: style-guide
title: Guide de Style
sidebar_label: Guide de Style
description: Standards de rédaction et de présentation pour la documentation Veza Platform
keywords: [veza, style, guide, writing, documentation, standards]
---

# 📝 Guide de Style

> **Standards de rédaction** pour la documentation Veza Platform - Cohérence, clarté et qualité

## 🎯 Principes Fondamentaux

### Clarté Avant Tout
- **Langage simple** : Éviter le jargon technique inutile
- **Phrases courtes** : Maximum 20 mots par phrase
- **Structure logique** : Progression naturelle des idées
- **Exemples concrets** : Illustrer chaque concept

### Cohérence Globale
- **Terminologie** : Utiliser les mêmes termes partout
- **Formatage** : Respecter les conventions établies
- **Navigation** : Structure uniforme des pages
- **Liens** : Interconnexion logique des contenus

## 📋 Structure des Pages

### Front-matter Obligatoire
```yaml
---
id: unique-identifier
title: Titre de la Page
sidebar_label: Label Court
description: Description SEO (160 caractères max)
keywords: [mot1, mot2, mot3]
---
```

### Structure du Contenu
```markdown
# Titre Principal (H1)

> **Sous-titre descriptif** - Contexte et objectif

## Section 1 (H2)

### Sous-section (H3)

#### Détail (H4)

## Voir Aussi

- `[Lien vers page connexe](/docs/section/page)`
- `[Lien externe](https://example.com)`
```

## ✍️ Règles de Rédaction

### Titres et En-têtes

#### Hiérarchie
- **H1** : Un seul par page, titre principal
- **H2** : Sections principales (2-5 par page)
- **H3** : Sous-sections (3-8 par section)
- **H4** : Détails techniques (si nécessaire)

#### Formatage
- **H1** : `# Titre Principal`
- **H2** : `## Section Principale`
- **H3** : `### Sous-section`
- **H4** : `#### Détail Technique`

### Paragraphes et Texte

#### Longueur
- **Paragraphes** : 3-5 phrases maximum
- **Lignes** : 80 caractères maximum
- **Phrases** : 20 mots maximum

#### Style
- **Voix active** : "Le système traite" au lieu de "Il est traité par le système"
- **Présent** : "Le système fonctionne" au lieu de "Le système fonctionnera"
- **Impératif** : "Exécutez la commande" pour les instructions

### Listes et Énumérations

#### Listes à Puces
```markdown
- **Élément principal** : Description détaillée
- **Élément secondaire** : Description courte
  - Sous-élément avec indentation
  - Autre sous-élément
```

#### Listes Numérotées
```markdown
1. **Étape 1** : Description de l'étape
2. **Étape 2** : Description de l'étape
   - Sous-étape optionnelle
   - Autre sous-étape
3. **Étape 3** : Description de l'étape
```

### Code et Exemples

#### Blocs de Code
```markdown
```bash
# Commentaire explicatif
commande --option valeur
```

```go
// Commentaire Go
func example() {
    return "Hello World"
}
```
```

#### Code Inline
```markdown
Utilisez la commande `make build` pour construire le projet.
```

### Tableaux

#### Format Standard
```markdown
| Colonne 1 | Colonne 2 | Colonne 3 |
|-----------|-----------|-----------|
| Donnée 1  | Donnée 2  | Donnée 3  |
| Donnée 4  | Donnée 5  | Donnée 6  |
```

#### Tableaux Complexes
```markdown
| Service | Port | Description | Statut |
|---------|------|-------------|--------|
| **API** | 8080 | API REST | ✅ Actif |
| **Chat** | 3001 | WebSocket | ✅ Actif |
| **Stream** | 3002 | Audio | ⚠️ En cours |
```

## 🎨 Éléments Visuels

### Emojis et Icônes

#### Usage Recommandé
- **Titres** : Un emoji par titre principal
- **Sections** : Emojis cohérents par type de contenu
- **Statuts** : ✅ ❌ ⚠️ 🔄 📊 🎯

#### Convention par Type
- **Architecture** : 🏗️ 🔧 ⚙️
- **Sécurité** : 🔒 🛡️ 🔐
- **Performance** : 📈 ⚡ 🚀
- **Documentation** : 📚 📝 📋
- **Tests** : 🧪 ✅ ❌
- **Déploiement** : 🚀 📦 🌐

### Admonitions et Alertes

#### Types Disponibles
```markdown
:::info Information
Contenu informatif important.
:::

:::tip Astuce
Conseil pratique pour l'utilisateur.
:::

:::warning Attention
Avertissement sur un point important.
:::

:::danger Danger
Information critique ou dangereuse.
:::
```

### Diagrammes Mermaid

#### Obligatoires pour
- **Architecture** : Diagrammes de composants
- **Flux** : Diagrammes de séquence
- **Données** : Diagrammes entité-relation
- **Processus** : Diagrammes de flux

#### Format Standard
```markdown
<MermaidDiagram>
  flowchart TB
    A[Composant A] --> B[Composant B]
    B --> C[Composant C]
</MermaidDiagram>
```

## 🔗 Gestion des Liens

### Liens Internes
```markdown
- [Titre de la page](/docs/section/page)
- [Section spécifique](/docs/section/page#section)
- [Fichier relatif](../other/page)
```

### Liens Externes
```markdown
- [Site externe](https://example.com)
- [Documentation externe](https://docs.example.com)
- [GitHub](https://github.com/veza-platform/veza-full-stack)
```

### Liens de Navigation
```markdown
## Voir Aussi

- [Page connexe](/docs/section/page)
- [Section parente](/docs/section)
- [Page suivante](/docs/section/next)
```

## 📝 Terminologie

### Termes Techniques

#### Backend
- **API** : Application Programming Interface
- **JWT** : JSON Web Token
- **REST** : Representational State Transfer
- **WebSocket** : Protocole de communication temps réel

#### Frontend
- **SPA** : Single Page Application
- **SSR** : Server-Side Rendering
- **CSR** : Client-Side Rendering
- **PWA** : Progressive Web App

#### Infrastructure
- **CI/CD** : Continuous Integration/Continuous Deployment
- **WAF** : Web Application Firewall
- **CDN** : Content Delivery Network
- **LB** : Load Balancer

### Conventions de Nommage

#### Fichiers et Dossiers
- **kebab-case** : `user-management.md`
- **PascalCase** : `UserManagement.tsx` (composants React)
- **lowercase** : `package.json` (fichiers de config)

#### Variables et Fonctions
- **camelCase** : `userName`, `getUserData()`
- **PascalCase** : `UserModel`, `UserService` (classes)
- **UPPER_SNAKE_CASE** : `API_BASE_URL` (constantes)

## 🎯 Qualité et Validation

### Checklist de Rédaction

#### Contenu
- [ ] **Titre clair** et descriptif
- [ ] **Introduction** qui explique l'objectif
- [ ] **Structure logique** des sections
- [ ] **Exemples concrets** pour chaque concept
- [ ] **Conclusion** ou prochaines étapes

#### Technique
- [ ] **Front-matter** complet et correct
- [ ] **Liens** fonctionnels et cohérents
- [ ] **Code** syntaxiquement correct
- [ ] **Diagrammes** Mermaid valides
- [ ] **Tableaux** bien formatés

#### Style
- [ ] **Orthographe** et grammaire correctes
- [ ] **Terminologie** cohérente
- [ ] **Ton** professionnel et accessible
- [ ] **Longueur** appropriée (500-2000 mots)
- [ ] **Navigation** "Voir aussi" présente

### Outils de Validation

#### Automatique
```bash
# Linter Markdown
npm run docs:lint

# Formatter Prettier
npm run fmt

# Validation complète
npm run docs:validate-full
```

#### Manuel
- **Relecture** : 2 personnes minimum
- **Test utilisateur** : Validation par un utilisateur externe
- **Review technique** : Validation par un expert technique

## 📚 Ressources et Références

### Documentation Externe
- [Docusaurus](https://docusaurus.io/docs)
- [Markdown Guide](https://www.markdownguide.org/)
- [Mermaid](https://mermaid-js.github.io/mermaid/)
- [Prettier](https://prettier.io/docs/en/)

### Outils Recommandés
- **Éditeur** : VS Code avec extensions Markdown
- **Linter** : markdownlint-cli
- **Formatter** : Prettier
- **Diagrammes** : Mermaid Live Editor

### Templates Disponibles
- `TEMPLATE-adr.mdx` : Architecture Decision Record
- `TEMPLATE-module.mdx` : Documentation de module
- `TEMPLATE-runbook.mdx` : Procédure opérationnelle
- `TEMPLATE-api-resource.mdx` : Documentation API

## 🔄 Évolution du Guide

### Processus de Mise à Jour
1. **Identification** d'un besoin de changement
2. **Proposition** via issue GitHub
3. **Discussion** avec l'équipe
4. **Validation** par les contributeurs
5. **Mise à jour** du guide
6. **Communication** aux utilisateurs

### Feedback et Amélioration
- **Issues** : [GitHub Issues](https://github.com/veza-platform/veza-full-stack/issues)
- **Discussions** : [GitHub Discussions](https://github.com/veza-platform/veza-full-stack/discussions)
- **PR** : Propositions d'amélioration

---

**Dernière mise à jour** : 2025-09-13  
**Version** : 1.0.0  
**Maintenu par** : Veza Platform Team