À propos de ce cours
Je suis Francis Bock, ingénieur et consultant IT, et je serai ravi de vous accompagner pour ce cours concernant la documentation de vos projets de code.
Ce cours est destiné aux développeurs et aux architectes logiciels de tous niveaux, qui souhaitent progresser dans la mise en place d’une documentation qui contribue efficacement à rendre le code de leurs projets, tant personnels que professionnels, réutilisable et maintenable.
Parlons tout d’abord de la structure de ce cours, afin que vous puissiez en tirer le maximum en toute autonomie !
Dans chacun des chapitres du cours, je vous explique les concepts du chapitre en détail, et je vous guide dans la mise en pratique de ces concepts.
Enfin, les quiz vous permettront de valider vos connaissances à la fin de chaque partie. Il y a deux quiz en tout, un pour chaque partie.
La partie 1, plutôt destinée aux développeurs, aborde les bonnes pratiques pour écrire une documentation qui rendra le code facilement réutilisable et maintenable.
La partie 2 se destine essentiellement aux architectes logiciels et traite des aspects techniques de la documentation pour les projets d’architecture.
Pourquoi écrire de la documentation ?
Documentez pour gagner du temps et créer de la cohérence
Si la documentation de votre projet est incomplète, ou si elle n'existe pas, les différentes parties prenantes comprendront le projet différemment, ce qui entraînera une mauvaise interprétation de la solution. Certains d'entre eux risquent d’avancer sur le projet dans la mauvaise direction et devront faire marche arrière. Cela entraînera une perte de temps et d'argent dans le projet, et démotivera les membres de l'équipe.
De la même manière, si vous ne disposez pas de documentation ou si elle est incomplète, vous devrez décrire la solution à chaque nouveau membre de l'équipe et aux prestataires externes, encore et encore. Ainsi, la documentation vous permet également de gagner du temps et d'assurer une certaine cohérence.
Documentez pour la lisibilité et la maintenabilité du code
Dans un contexte de collaboration en équipe sur un même projet, comme cela vous est arrivé ou vous arrivera certainement, vous ne pouvez pas vous permettre d'être ralenti ou bien bloqué longtemps par un code mal écrit ou mal formaté.
Travailler en équipe implique de nombreux changements sur le code, et si votre code est trop peu lisible, cela entraînera une perte de productivité de l’équipe. Cette situation serait difficilement tenable sur le long terme. C’est pourquoi votre code doit être formaté, écrit et documenté selon des règles communes qui permettent à tout nouveau membre de comprendre les exigences de l’équipe.
Le coût d’un code non documenté
J'espère que le paragraphe précédent vous a convaincu de l’importance de la qualité du code et de la documentation sur la productivité de l’équipe. Il faut également avoir à l’esprit que plus cette situation serait amenée à durer, plus le coût pour revenir à une situation saine serait important. Plus vous documentez votre code rapidement, plus ça sera facile et rapide à faire.
La bonne attitude à avoir à propos de la documentation
Plus que d’écrire de la documentation, il est crucial d’adopter la bonne attitude lorsqu’on est confronté à des projets de code. Je vous livre ici quelques idées qui seront complétées dans la suite du cours.
Codez pour l’équipe
La première attitude que je trouve importante et que vous aurez devinée en lisant les paragraphes précédents, c’est que vous codez pour l’équipe, pas pour vous. C’est pour ça qu’il vous faut de la rigueur dans votre développement et votre documentation, afin qu'elle soit compréhensible par tous.
Ajustez la quantité et la qualité
La juste attitude consiste également à trouver un compromis en termes de qualité et de quantité par rapport au coût que représente la documentation. Il faut être conscient qu’écrire de la documentation et du code correctement formatés a un certain coût. À vous de trouver le juste équilibre grâce aux outils et exemples de ce cours !
Maintenez votre documentation
Enfin, il n’est pas suffisant d’écrire proprement, il faut garder votre documentation dans cet état au cours du temps ! Il est donc nécessaire de maintenir votre documentation, de la mettre à jour régulièrement, tout comme du code. On peut même viser à améliorer la lisibilité au cours du temps. C’est là une véritable démarche professionnelle de développeur.
En résumé
Une documentation exhaustive et adaptée, c’est :
un gain de cohérence, en particulier en environnement partagé ;
un code plus lisible et maintenable ;
une économie de temps en évitant les coûts liés aux corrections multiples ;
adopter une attitude professionnelle au profit de l’équipe en équilibrant qualité et quantité.
Maintenant que vous avez une bonne idée de ce qui vous attend dans le cours mais également des principaux enjeux autour de la documentation, commençons à regarder de près comment écrire la documentation d’un projet afin d’en tirer le meilleur. C'est l'objet du chapitre suivant !
Vous êtes prêt ? Alors je vous propose de me rejoindre dès maintenant dans le prochain chapitre !
