Dans ce module, tu mets en place une documentation de projet qui va au-delà du code lui-même. Tu organises à la fois une documentation technique, une documentation générée automatiquement à partir des commentaires du code et un manuel utilisateur pour ton application.

L’objectif n’est pas d’écrire un énorme document théorique, mais de produire une documentation utile, à jour et facile à retrouver pour l’équipe et pour les personnes qui voudront reprendre ton projet plus tard.

Organisation générale de la documentation

Toute la documentation du projet doit être rangée dans un dossier docs/ à la racine de ton dépôt. Tu peux ensuite organiser ce dossier par type de documentation.

• docs/technique/ : documents sur l’architecture, les choix techniques importants, les modèles de données, les principaux flux, etc.
• docs/utilisateur/ : guide de prise en main, captures d’écran, explication des fonctionnalités vues par l’utilisateur.
• docs/api/ (ou autre nom explicite) : documentation générée automatiquement depuis le code avec un outil comme Doxygen.
• Au besoin, d’autres sous-dossiers pour des besoins spécifiques (par exemple docs/tests pour des plans de tests plus détaillés).

Documentation technique “à la main”

La documentation technique complète ce que l’on voit dans le code. Elle explique les grandes décisions et donne une vue d’ensemble que l’on ne peut pas deviner en lisant seulement les fichiers source.

• Décris l’architecture générale de ton application (schémas simples, composants principaux, interactions).
• Note les décisions techniques importantes (par exemple le choix d’un framework ou d’un design particulier) et leurs raisons.
• Présente les principaux modèles de données ou formats d’échange (API, fichiers, messages, etc.).
• Mets ces éléments dans des fichiers lisibles (par exemple .md) dans docs/technique/, avec des titres clairs pour qu’on les retrouve facilement.

Documentation générée à partir du code (Doxygen)

En plus de la doc écrite à la main, tu peux générer automatiquement une documentation de ton code à partir de commentaires structurés. Un outil classique pour ça est Doxygen.

• Ajoute des commentaires Doxygen sur certaines parties importantes de ton code (fonctions, classes, modules) en utilisant des balises comme @brief pour un résumé et une description plus détaillée en dessous.
• Crée un fichier de configuration Doxygen (souvent nommé Doxyfile) ou un script minimal qui indique à Doxygen où trouver ton code et où générer la documentation (par exemple dans docs/api/).
• Documente dans ton projet comment lancer la génération (commande à exécuter, dossier de sortie), pour que les autres puissent régénérer la doc à partir du code.
• Rappelle-toi que cette doc générée ne remplace pas la documentation technique : elle la complète en donnant une vue détaillée des fonctions et classes réellement présentes dans le code.

Manuel utilisateur

Le manuel utilisateur sert à expliquer ton application à quelqu’un qui ne connaît pas le projet et qui ne lit pas le code. Il doit être simple, concret et illustré.

• Prévois un guide de démarrage rapide qui explique comment installer, lancer et utiliser les fonctionnalités principales de l’application.
• Ajoute des sections par fonctionnalité importante avec des captures d’écran et des étapes numérotées.
• Range ces fichiers dans docs/utilisateur/ et utilise une structure de titres qui suit les menus ou les écrans de ton application, pour que l’utilisateur s’y retrouve facilement.

Ce qui est attendu à ce stade du projet

Au moment où tu travailles sur cette page, on ne s’attend pas à ce que toute la documentation soit parfaite et terminée. En revanche, certaines bases doivent déjà être en place.

• Le dossier docs/ existe, avec au moins les sous-dossiers technique et utilisateur, et éventuellement un dossier pour la documentation générée par Doxygen.
• Une première version de la documentation technique est présente (même partielle), décrivant au moins l’idée générale de l’architecture et quelques décisions clés.
• Un début de manuel utilisateur est créé, avec un mini guide de démarrage rapide ou la description d’un parcours utilisateur simple.
• Si tu utilises Doxygen ou un outil similaire, la configuration minimale est en place et tu es capable de générer une documentation HTML à partir des commentaires du code pour au moins une partie du projet.