📚 Maintenance de la Documentation

🎯 Vue d'ensemble

En tant que superadmin, vous êtes responsable de maintenir la documentation à jour avec des captures d'écran et des diagrammes.

Cette page sert également de mémo pour les fonctionnalités clés à documenter, notamment :

• La création et l'assignation des actions (plans d'action)
• L'intégration avec le calendrier
• La gestion des lots d'actions (batchs)

📸 Gestion des Captures d'Écran

Outils nécessaires

Windows 11

• Outil Capture : Win + Shift + S (natif)
• ShareX (recommandé) : https://getsharex.com/
• ScreenToGif : Pour les animations GIF

Installation ShareX

1. Télécharger depuis https://getsharex.com/
2. Installer l'application
3. Configurer :
4. Format : PNG
5. Qualité : 90%
6. Destination : Dossier personnalisé

Préparation

Checklist avant de commencer

• [ ] Serveur démarré (.\scripts\dev.ps1 -Start)
• [ ] Données de démo créées
• [ ] Navigateur en mode normal (pas d'extensions visibles)
• [ ] Résolution écran : 1920x1080 ou 1280x720
• [ ] Zoom navigateur : 100%
• [ ] Fond d'écran neutre

Organisation des fichiers

backend/app/documentation/images/
├── user/                    # Captures utilisateur
│   ├── creer-etude-01.png
│   ├── creer-etude-02.png
│   ├── plan-action-kanban.png
│   ├── plan-action-dragdrop.gif
│   └── historique-versions.png
├── validateur/              # Captures validateur
│   ├── valider-etude.png
│   ├── invalider-commentaire.png
│   └── suivi-demandes.png
├── admin/                   # Captures admin
│   ├── creer-utilisateur.png
│   ├── gerer-services.png
│   └── affecter-referentiels.png
├── superadmin/              # Captures superadmin
│   ├── creer-organisation.png
│   ├── gestion-referentiels.png
│   └── bibliotheque-questions.png
└── workflow/                # Diagrammes
    ├── workflow-complet.png
    └── workflow-complet.drawio

Liste des captures à réaliser

🔴 Priorité Haute (14 captures + nouvelles vues Actions/Calendrier)

Utilisateur (5 captures)

1. creer-etude-01.png - Formulaire de création d'étude
2. Page : /studies/create

3. Contenu : Sélection référentiel, champ nom, bouton créer

4. creer-etude-02.png - Questionnaire en cours

5. Page : /studies/{id}/edit

6. Contenu : Questions, boutons réponse, barre progression

7. plan-action-kanban.png - Vue Kanban

8. Page : /studies/{id} (onglet Plan d'action)

9. Contenu : Colonnes Kanban, cartes d'actions, compteurs

10. plan-action-dragdrop.gif - Animation drag & drop

11. Page : /studies/{id} (onglet Plan d'action)

12. Contenu : Déplacement d'une carte entre colonnes

13. historique-versions.png - Liste des versions

14. Page : /studies/{id} (onglet Historique)
15. Contenu : Versions, dates, auteurs, types

Validateur (3 captures)

1. valider-etude.png - Bouton de validation
2. Page : /studies/{id} (onglet Résultats)

3. Contenu : Bouton valider, score, graphique

4. invalider-commentaire.png - Modal d'invalidation

5. Page : Modal d'invalidation

6. Contenu : Champ commentaire, bouton invalider

7. suivi-demandes.png - Liste des études en attente

8. Page : /studies (filtré)
9. Contenu : Liste études, filtres, statuts

Admin (3 captures)

1. creer-utilisateur.png - Formulaire création utilisateur
2. Page : /organisation-users (modal)

3. Contenu : Champs formulaire, sélecteur rôle

4. gerer-services.png - Liste des services

5. Page : /services

6. Contenu : Liste services, boutons actions

7. affecter-referentiels.png - Affectation référentiels

8. Page : /admin/assign-norms
9. Contenu : Sélection organisation, checkboxes

Superadmin (3 captures)

1. creer-organisation.png - Formulaire création organisation
2. Page : /organisations (modal)

3. Contenu : Formulaire complet, sélecteur statut

4. gestion-referentiels.png - Liste des référentiels

5. Page : /admin/norms

6. Contenu : Liste référentiels, actions

7. bibliotheque-questions.png - Bibliothèque de questions

8. Page : /admin/questions
9. Contenu : Liste questions, filtres

Actions & Calendrier (nouvelles captures)

1. plan-action-creation-assignment-scopes.png
2. Page : /admin/action-plans/{id} (modal "Nouvelle action")

3. Contenu : champs principaux + liste des scopes d'assignation :

   • 👤 Utilisateur individuel
   • 👥 Tous les utilisateurs d'un rôle (superadmin)
   • 🏛️ Service entier
   • 🏢 Organisation entière (avec sélecteur d'organisation pour superadmin)
   • 🌍 Tous les utilisateurs de la plateforme

4. plan-action-detail-batch.png

5. Page : /admin/action-plans/{id}

6. Contenu :

   • Une ligne "Lot d'assignation" dans le tableau des actions
   • Badge "X actions individuelles"
   • Bloc déployé montrant les actions détaillées (utilisateurs, priorités, échéances)

7. calendrier-actions-auto.png

8. Page : /calendar
9. Contenu :
   • Événements d'actions créés automatiquement (avec préfixe 📋)
   • Exemple d'action datée (due_date) + action sans due_date (positionnée à aujourd'hui)
   • Si possible, un exemple issu d'une assignation de masse (plusieurs utilisateurs le même jour)

Bonnes pratiques

Format et qualité

• Format : PNG pour images statiques
• Format : GIF pour animations (< 5 Mo)
• Résolution : 1920x1080 ou 1280x720
• Compression : Optimiser avec TinyPNG
• Taille : < 500 Ko par image

Contenu

• ✅ Masquer les données sensibles
• ✅ Utiliser des données de démo
• ✅ Annoter les points importants (flèches, encadrés)
• ✅ Fond d'écran neutre
• ✅ Zoom sur les éléments importants

Nommage

• Format : [section]-[action]-[numero].png
• Exemples :
• creer-etude-01.png
• plan-action-kanban.png
• valider-etude.png

Intégration dans la documentation

Syntaxe Markdown

![Description](../images/user/creer-etude-01.png)

Avec légende

![Création d'une étude](../images/user/creer-etude-01.png)
*Figure 1 : Page de création d'une nouvelle étude*

GIF animé

![Drag & Drop](../images/user/plan-action-dragdrop.gif)
*Animation : Déplacer une action par drag & drop*

Mise à jour

Quand mettre à jour les captures

• Changement majeur d'interface
• Nouvelles fonctionnalités
• Correction de bugs visuels
• Feedback utilisateurs

Processus de mise à jour

1. Identifier les captures obsolètes
2. Préparer l'environnement
3. Réaliser les nouvelles captures
4. Optimiser les images
5. Remplacer dans le dossier images/
6. Vérifier l'affichage dans la doc

🎨 Gestion des Diagrammes

Outil : draw.io

Accès

https://app.diagrams.net/

Avantages

• ✅ Gratuit et en ligne
• ✅ Pas d'installation nécessaire
• ✅ Export multiple formats
• ✅ Sauvegarde locale (.drawio)

Configuration du Canvas

Nouveau diagramme

1. Aller sur https://app.diagrams.net/
2. Cliquer sur "Create New Diagram"
3. Sélectionner "Blank Diagram"
4. Nommer : workflow-complet

Paramètres

• Taille : 1200 x 2400 px
• Grille : Activée (20px)
• Snap to Grid : Activé
• Background : Blanc

Palette de couleurs

Par rôle

• Superadmin : #3498db (Bleu)
• Admin : #2ecc71 (Vert)
• Validateur : #f39c12 (Orange)
• Utilisateur : #e74c3c (Rouge)
• Processus : #95a5a6 (Gris)

Texte

• Couleur : Blanc (#FFFFFF)
• Police : Arial
• Taille : 14pt (titres), 12pt (contenu)

Formes à utiliser

Rectangles arrondis (Étapes)

• Largeur : 200px
• Hauteur : 60px
• Rayon : 10px
• Bordure : 2px, #2c3e50

Losanges (Décisions)

• Largeur : 150px
• Hauteur : 100px
• Bordure : 2px, #2c3e50

Flèches (Connexions)

• Épaisseur : 2px
• Couleur : #34495e
• Style : Ligne droite avec flèche

Structure du diagramme

Phase 1 : Configuration (Superadmin)

SUPERADMIN (Bleu)
    ↓
Créer Organisation
    ↓
Affecter Référentiels
    ↓

Phase 2 : Gestion (Admin)

ADMIN (Vert)
    ↓
Créer Services
    ↓
Créer Utilisateurs
    ↓

Phase 3 : Évaluation (Utilisateur)

UTILISATEUR (Rouge)
    ↓
Créer Étude
    ↓
Remplir Questionnaire
    ↓
Demander Validation
    ↓

Phase 4 : Validation (Validateur)

VALIDATEUR (Orange)
    ↓
┌────┴────┐
│         │
▼         ▼
Valider  Invalider
  ✅       ❌
  │        │
  │        └──► Corrections ──┐
  │                           │
  └───────────────────────────┘
              ↓

Phase 5 : Suivi (Utilisateur)

Plan d'Action (Rouge)
    ↓
Historique
    ↓
Exports

Icônes à utiliser

• 🔧 Superadmin
• 👨‍💼 Admin
• ✅ Validateur
• 👤 Utilisateur
• 📝 Créer
• 📊 Résultats
• 📋 Plan d'action
• 📸 Version
• ✅ Valider
• ❌ Invalider

Export

Format PNG (recommandé)

1. File → Export as → PNG
2. Résolution : 300 DPI
3. Transparent background : Non
4. Border width : 10px
5. Nom : workflow-complet.png
6. Emplacement : backend/app/documentation/images/workflow/

Format SVG (optionnel)

1. File → Export as → SVG
2. Embed fonts : Oui
3. Nom : workflow-complet.svg

Sauvegarder le fichier source

1. File → Save as
2. Format : .drawio
3. Nom : workflow-complet.drawio
4. Emplacement : Même dossier que les exports

⚠️ Important : Toujours sauvegarder le fichier .drawio pour faciliter les modifications futures !

Intégration dans la documentation

Dans workflow.md

## 📊 Diagramme Visuel

![Workflow de la plateforme](../images/workflow/workflow-complet.png)
*Figure 1 : Workflow complet de la plateforme*

Mise à jour

Quand mettre à jour le diagramme

• Ajout d'une nouvelle phase
• Modification du workflow
• Nouveau rôle
• Changement majeur de processus

Processus de mise à jour

1. Ouvrir le fichier workflow-complet.drawio
2. Effectuer les modifications
3. Exporter en PNG (300 DPI)
4. Remplacer l'ancien PNG
5. Vérifier l'affichage dans la documentation
6. Sauvegarder le .drawio mis à jour

📋 Checklist de Maintenance

Mensuelle

• [ ] Vérifier que toutes les captures sont à jour
• [ ] Vérifier que le diagramme reflète le workflow actuel
• [ ] Optimiser les images trop lourdes
• [ ] Vérifier les liens dans la documentation

Après chaque mise à jour majeure

• [ ] Identifier les captures impactées
• [ ] Réaliser les nouvelles captures
• [ ] Mettre à jour le diagramme si nécessaire
• [ ] Tester l'affichage dans tous les navigateurs

Annuelle

• [ ] Refaire toutes les captures avec le design actuel
• [ ] Recréer le diagramme si changements importants
• [ ] Archiver les anciennes versions
• [ ] Documenter les changements

🛠️ Outils Recommandés

Captures d'écran

• ShareX : https://getsharex.com/ (Windows)
• Greenshot : https://getgreenshot.org/ (Windows)
• ScreenToGif : https://www.screentogif.com/ (GIF)

Édition d'images

• Paint.NET : https://www.getpaint.net/ (Windows)
• GIMP : https://www.gimp.org/ (Multiplateforme)

Compression

• TinyPNG : https://tinypng.com/ (En ligne)
• ImageOptim : https://imageoptim.com/ (Mac)

Diagrammes

• draw.io : https://app.diagrams.net/ (En ligne)
• Excalidraw : https://excalidraw.com/ (En ligne, style dessiné)

❓ Questions fréquentes

Q : Quelle résolution pour les captures ?
R : 1920x1080 ou 1280x720, selon la taille de votre écran.

Q : Comment annoter les captures ?
R : Utiliser ShareX ou Paint.NET pour ajouter flèches et encadrés.

Q : Faut-il refaire toutes les captures après chaque mise à jour ?
R : Non, seulement celles des pages modifiées.

Q : Le diagramme doit-il être en PNG ou SVG ?
R : PNG pour la compatibilité, mais garder le .drawio pour les modifications.

Q : Comment optimiser les GIF ?
R : Limiter à 5 secondes, réduire la résolution, supprimer les frames inutiles.

Q : Où trouver les données de démo ?
R : Organisation "Démo SA" créée automatiquement au démarrage.

📞 Support

Pour toute question sur la maintenance de la documentation :
- Consulter backend/app/documentation/images/README.md
- Consulter backend/app/documentation/GUIDE_CAPTURES.md
- Consulter backend/app/documentation/images/workflow/INSTRUCTIONS_DRAWIO.md