Des ressources pour générer automatiquement la documentation de vos prochains projets

Le 10/01/2017

Aujourd'hui, le BlogDuWebdesign vous propose de découvrir ou redécouvrir une pratique qui fera le bonheur de vos collaborateurs futurs : la génération de documentations pour vos projets.

Pourquoi documenter ses projets

Quand je parle de documenter ses projets, je pense que la plupart d'entre vous pensent à des projets publiques ou open source. Si effectivement la documentation est nécessaire dans ce genre de projet pour permettre à la communauté de comprendre le fonctionnement de votre programme/ressource sans passer par le code source, elle peut être tout aussi nécessaire pour des projets en interne, même si vous êtes le seul développeur présent.

Documenter un projet permet de s'assurer que son fonctionnement restera clair et compréhensible, et ce même dans plusieurs années. De plus, la documentation est une tâche qui vous forcera à commenter votre code, ce qui vous encouragera à écrire un code plus lisible et concis.

Attention, je ne dis tout de même pas qu'il est nécessaire de documenter TOUS les projets que vous réalisez. Même si cela serait sûrement un plus, il faut prendre en compte que cette opération demande du temps, et que vous aurez beaucoup de mal à le facturer à votre client pour les projets les plus modestes.

Je vous conseille personnellement d'essayer de documenter tous les projets atypiques avec une forte durée de vie mais un rythme de modification assez faible. Inutile de documenter un thème wordpress suivant les standards pour un simple site vitrine par exemple, alors qu'un projet Electron permettant de gérer les stocks d'un restaurant aura toutes les raisons de l'être. Au final, c'est à chacun d'estimer si son projet a suffisamment de raisons d'être documenté pour consacrer du temps à cette tâche.

Des générateurs de documentation statiques

Pour documenter un projet, il serait bien sûr possible de créer nous-mêmes un petit site en HTML, y écrire une documentation et la maintenir à jour à chaque changement de version, mais cela prendrait beaucoup trop de temps. L'idéal pour cette tâche est d'utiliser un outil permettant de générer et mettre à jour directement une documentation, dont vous pourrez retrouver 5 exemples dans la liste juste en dessous.

Atomic

Couscous

Docsify

Daux

MkDocs

Bonus : Git changelog

Nous ne sommes pas ici en présence d'un générateur de documentation mais d'un générateur de Changelog. En effet, Git change log va regarder tous les commit et leurs messages entre vos deux numéros de version, et générer ensuite un changelog ainsi qu'un résume à ce changelog.

Pratique pour gagner du temps et éviter d'oublier des choses !