Gestion de projet : Documenter efficacement une application frontend

Mise à jour le 10 Oct 2024

La documentation d’une application frontend est essentielle pour garantir une bonne compréhension du projet par les nouveaux développeurs et faciliter leur onboarding. Une documentation claire et détaillée leur permet de saisir rapidement l’architecture, les outils utilisés, et les pratiques recommandées pour maintenir ou étendre le projet.

L’objectif est de permettre à un nouveau venu de se familiariser rapidement avec l’architecture, les outils utilisés, les flux de travail et les pratiques de développement sans être submergé de détails inutiles.

Prérequis

Avant de commencer à documenter votre projet, il est important de choisir la plateforme la plus adaptée pour héberger la documentation en fonction de la taille et des besoins du projet :

• Un README dans le dépôt Git pour les projets simples.
• Un wiki GitHub/GitLab pour des projets plus complexes.
• Un générateur de documentation comme VuePress ou Docusaurus pour des projets ayant besoin d’une documentation structurée et accessible en ligne.
• WordPress avec le plugin EazyDocs pour des projets nécessitant une documentation enrichie et facilement gérable via un CMS.

Use case

Avant de commencer la rédaction de la documentation, il est important que le projet soit bien structuré. Une bonne organisation facilite non seulement la compréhension du projet, mais aussi sa maintenance et son évolution. Il est important de gérer efficacement les différents environnements (développement, test, production) en utilisant, par exemple, des fichiers .env pour configurer les variables spécifiques à chaque environnement. Les fichiers et répertoires doivent être organisés de manière logique, reflétant clairement les différentes parties de l’application. Cette structure permettra de mieux naviguer dans le code, de faciliter les mises à jour et de garantir une documentation cohérente et précise.

Documentation dans le dépôt

Si vous optez pour une documentation en ligne, pensez à inclure un lien clair vers celle-ci dans votre dépôt principal, afin que les développeurs sachent où chercher.

Exemple :

## Documentation

Toute la documentation du projet est disponible [ici](https://example.com/docs).

Pour commencer rapidement, consultez le [Guide d'installation rapide](https://example.com/docs/installation).

Contexte du projet

Le point de départ de toute bonne documentation est un guide d’introduction clair et concis. Celui-ci doit répondre aux questions suivantes :

• De quoi s’agit-il ? Donnez une vue d’ensemble du projet et de son but. Évitez d’entrer trop dans les détails techniques dès le début.
• Quelles sont les technologies utilisées ? Listez les frameworks et bibliothèques clés utilisés dans le projet (par exemple, Vue.js 3, Pinia, Axios, Vitest). Assurez-vous d’indiquer la version de chaque technologie.
• Quels sont les prérequis ? Mentionnez les outils que le développeur doit installer avant de pouvoir démarrer (Node.js, npm, Git, etc.).

Exemple :

# Introduction

Cette application est construite avec Vue.js 3 et communique avec un backend Drupal 10 via une API REST. Nous utilisons Pinia pour la gestion d'état globale, Axios pour les requêtes HTTP, et Vitest pour les tests unitaires.

## Prérequis
- Node.js (v14 ou supérieur)
- npm ou yarn
- Git

Structurer les dossiers

Il est important que la structure de votre projet soit compréhensible. Documentez succinctement chaque dossier et fichier clé pour expliquer à quoi il sert.

N’écrivez pas une documentation exhaustive pour chaque fichier, mais fournissez une vue d’ensemble logique. Cela permet de comprendre où les composants, les stores ou les tests se trouvent.

Exemple :

## Structure des dossiers
src/
├── components/
│   └── # Composants Vue.js réutilisables
├── store/
│   └── # Dossier contenant les stores Pinia pour la gestion d'état
├── views/
│   └── # Pages principales de l'application
├── api/
│   └── # Fichiers pour gérer les appels API avec Axios
└── router/
    └── # Configuration du routage de l'application
tests/
└── # Fichiers de tests unitaires avec Vitest

Exemple de fonctionnalité

Documentez comment implémenter une fonctionnalité dans votre application, en montrant comment les différents fichiers du module sont répartis à travers les dossiers du projet. Voici un exemple de mise en œuvre d’une fonctionnalité de connexion dans une application Vue.js 3, utilisant Pinia pour la gestion d’état, Axios pour les requêtes API et Vitest pour les tests.

Exemple :

### Objectif
Permettre aux utilisateurs de se connecter en envoyant leurs informations d'identification à un endpoint API et en stockant le token de session dans le store global.

### Structure des fichiers
Organisez les fichiers du module comme suit :

src/
│
├── components/
│   └── LoginForm.vue  # Composant Vue.js pour le formulaire de connexion
├── store/
│   └── authStore.js   # Store Pinia pour gérer l'état d'authentification
├── views/
│   └── LoginPage.vue  # Page Vue.js intégrant le composant LoginForm
├── api/
│   └── authApi.js     # Module Axios pour les requêtes liées à l'authentification
└── router/
    └── # Configuration du routage de l'application
tests/
└── # Fichiers de tests unitaires avec Vitest

Documenter le Design System

Documentez l’intégration du design system dans votre application frontend pour assurer une cohérence visuelle et une expérience utilisateur uniforme. Expliquez comment le design system est utilisé pour créer des composants réutilisables et gérer les styles à travers l’application.

Le design system permet de maintenir une cohérence visuelle à travers l’application en fournissant un ensemble de composants UI, des règles de style et des pratiques recommandées. Il facilite également la création de nouvelles fonctionnalités en utilisant des composants préconçus et des styles uniformisés. Décrivez les principaux composants et styles fournis par le design system et comment les utiliser.

Lors de la création de nouveaux composants, utilisez les composants et les styles définis dans le design system. Par exemple, au lieu de créer des boutons personnalisés, utilisez le composant Button.vue pour garantir une apparence cohérente à travers l'application. Voici les éléments typiques que vous pourriez utiliser : 

- Composants UI : Boutons, formulaires, modals, cartes, etc.
- Guidelines de Style : Couleurs, typographie, espacements, etc.
- Patterns de Conception : Utilisation de composants dans des scénarios réels pour garantir une expérience utilisateur cohérente.

Expliquer les dépendances

Si votre application utilise des bibliothèques ou des services externes, assurez-vous de documenter pourquoi elles sont utilisées et comment elles s’intègrent dans le projet. Ne documentez pas tout leur fonctionnement interne, mais concentrez-vous sur les aspects pertinents pour le projet.

Par exemple, si vous utilisez Axios pour effectuer des requêtes API, mentionnez simplement où et comment les développeurs peuvent le configurer, sans détailler toute la documentation d’Axios elle-même.

Exemple :

## Requêtes HTTP avec Axios

Nous utilisons Axios pour gérer toutes les requêtes HTTP vers l'API de Drupal 10. Les configurations d'Axios sont centralisées dans le dossier `src/api/axios.js`, où vous pouvez modifier l'URL de base ou ajouter des interceptors pour gérer les erreurs globales.

Documenter le flux de développement

Le flux de développement et les conventions de contribution doivent être clairs pour que les nouveaux développeurs puissent se conformer aux règles du projet.

Mentionnez les branches Git, le style de codage, les processus de revue de code, les tests automatisés, et les outils de CI/CD. Il est important d’indiquer comment soumettre des fonctionnalités ou des corrections de bugs.

Exemple :

## Flux de développement

1. Clonez le projet avec `git clone`.
2. Créez une nouvelle branche pour chaque fonctionnalité ou bugfix à partir de la branche `main`.
3. Faites vos changements et poussez-les.
4. Ouvrez une pull request et suivez le processus de revue de code.

## Style de codage

Le projet utilise ESLint et Prettier pour garantir un style de codage cohérent. Assurez-vous d’exécuter `npm run lint` avant de pousser vos modifications.

Éviter la surdocumentation

Il est facile de tomber dans le piège de surdocumenter. Se concentrer sur l’essentiel permet de garder la documentation légère et pertinente.

• Ne documentez pas ce qui est évident : Si une fonctionnalité ou un aspect du projet est bien couvert par la documentation officielle d’une bibliothèque, il n’est pas nécessaire de le répéter. Au lieu de cela, fournissez des liens vers les ressources externes.
• Concentrez-vous sur les spécificités du projet : La documentation doit être spécifique à votre application. Par exemple, documentez comment Pinia est utilisé pour gérer l’état dans votre application, pas comment Pinia fonctionne en général.

Exemple :

## Gestion d'état avec Pinia

Nous utilisons Pinia pour gérer l’état global de l’application. Tous les stores sont placés dans `src/store/`. Voici un exemple d'utilisation dans un composant :

import { useUserStore } from '@/store/userStore';
const userStore = useUserStore();

Pour plus d'informations sur Pinia, consultez la [documentation officielle](https://pinia.vuejs.org/).

Maintenir la documentation

L’un des plus grands défis avec la documentation est de la maintenir à jour. Si elle devient obsolète, elle peut causer plus de confusion que de clarté. Il est donc essentiel d’intégrer la mise à jour de la documentation dans votre flux de travail quotidien, en particulier lors des changements majeurs dans l’application.

Voici quelques bonnes pratiques à suivre :

Intégrer la documentation dans les revues de code

Lorsque vous ajoutez de nouvelles fonctionnalités ou modifiez des aspects importants du projet, veillez à inclure les mises à jour de la documentation dans les pull requests. Cela garantit que la documentation évolue avec le projet.

Utiliser un processus de validation automatique

En plus d’inclure des tests dans votre pipeline de CI/CD, vous pouvez automatiser certaines vérifications de la documentation. Par exemple :

• Assurez-vous que toutes les commandes mentionnées dans la documentation fonctionnent correctement.
• Utilisez des outils qui valident la présence de fichiers essentiels (README, instructions de démarrage, etc.) avant la fusion d’une pull request.

Impliquer l’équipe dans la documentation

Encouragez tous les membres de l’équipe à contribuer à la documentation. Cela peut inclure la création d’une “culture de documentation” où chaque développeur est responsable de documenter les fonctionnalités qu’il ou elle implémente.

Datez les sections importantes

Ajoutez des dates ou des informations sur la version du projet à des sections clés de la documentation, afin que les nouveaux arrivants puissent rapidement savoir si la documentation qu’ils lisent est encore d’actualité.

Exemple :

## Gestion d'état avec Pinia (Mise à jour en Septembre 2024)

La gestion d'état globale de l'application est effectuée avec Pinia. Depuis la version 1.2.0 de l'application, nous avons introduit un nouveau store pour gérer les préférences utilisateur.

Documenter la mise en production et CI

Outre la documentation sur le développement, il est crucial de fournir des informations sur le processus de déploiement, la gestion des environnements et les tests dans un cadre de production. Une application bien documentée doit non seulement permettre à un développeur de travailler localement, mais aussi de comprendre comment ses modifications affecteront l’application en production.

Pipeline de déploiement

Expliquez comment l’application passe de l’environnement de développement à la production. Si vous utilisez des outils comme Docker, GitLab CI, ou un service cloud pour les déploiements, mentionnez-les, mais concentrez-vous uniquement sur l’essentiel : ce qu’il faut faire pour déployer une nouvelle version.

Exemple :

## Déploiement de l'application

Notre pipeline de CI/CD est géré via GitLab CI. Après la fusion dans la branche `main`, le pipeline s'exécute automatiquement pour :
- Lancer les tests unitaires via Vitest.
- Compiler l'application Vue.js avec Webpack.
- Déployer l'application sur le serveur de production via Docker.

### Commandes utiles

- `npm run build`: Génère une version optimisée de l'application.
- `npm run test`: Lance les tests unitaires.

Gestion des environnements

Documentez comment gérer les différentes configurations entre les environnements de développement, de test et de production. Par exemple, vous pourriez expliquer comment utiliser des fichiers .env pour configurer les URLs API en fonction de l’environnement.

Exemple :

## Configuration des environnements

Nous utilisons des variables d'environnement pour gérer les différences entre développement et production. Ces variables sont définies dans des fichiers .env.

- .env.development : Configuration locale avec l'URL de l'API de développement.
- .env.production : Configuration pour l'API en production.

Lors du build, assurez-vous que le fichier correct est utilisé :
npm run build --mode production

Guides pratiques et FAQ

Une documentation utile ne se limite pas à décrire la structure et les outils, elle doit également contenir des guides pratiques ou une section FAQ. Celles-ci doivent répondre aux questions ou aux problèmes courants rencontrés lors du développement ou de l’intégration.

Exemple :

## FAQ

### Comment ajouter un nouveau store Pinia ?

1. Créez un fichier dans `src/store/` avec le nom du store.
2. Utilisez `defineStore` pour définir votre store.
3. Importez le store dans le composant où il est nécessaire.

### Comment ajouter une nouvelle requête API ?

1. Ajoutez la nouvelle requête dans `src/api/axios.js`.
2. Utilisez Axios pour appeler l'API dans votre store ou composant.

Tester le projet

Mentionnez l’importance des tests, surtout si votre projet utilise un framework de test comme Vitest. Expliquez comment les nouveaux développeurs peuvent exécuter et écrire des tests.

Exemple :

## Tests unitaires avec Vitest

Tous les tests unitaires sont écrits avec Vitest et placés dans le dossier `tests/`. Pour lancer les tests, utilisez la commande suivante :

npm run test

Ajoutez des tests pour chaque composant critique ou logique métier dans l'application.

Conclusion

Une bonne documentation ne signifie pas une documentation exhaustive. En vous concentrant sur l’essentiel, vous rendez votre projet plus facile à comprendre et à maintenir pour un nouveau développeur. Structurez l’information de manière claire, concentrez-vous sur les spécificités de votre projet, et évitez de surcharger la documentation avec des informations déjà disponibles dans les documentations officielles des outils utilisés.

Soyez concis, précis, et guidez les développeurs avec des exemples pratiques.