Écrire la doc ? Oui mais avec une bonne stratégie et mkdocs !

De la documentation technique ou non technique comme les règles métier et les process, j’en ai écris des kilomètres et sur plein d’outil différents.

Le truc c’est qu’il faut arriver à versionner sa documentation et qu’il soit relativement aisé de la mettre la jour. C’est pourquoi la documentation à l’intérieur du dépôt de code semble une bonne idée:

  • Profite de votre versionning nativement
  • À chaque pull request ou merge request on peut vérifier si la documentation continue à être mis à jour
  • On l’écrit en markdown pour faciliter la relecture en équipe

En pratique c’est un peu plus galère :

  • On travaille souvent sur plusieurs dépôt (front et back séparé) du coup où mettre la documentation un peu plus transverse ?
  • Vu que vous fonctionnez par pull request un non tech doit en faire une pour mettre à jour la doc. Quel galère à tout lui expliquer, du coup ses PR sont fusionnées souvent sur le tard et n’ont pas été embarqué dans la livraison.. et juste du markdown pour voir à quoi ça ressemble dans l’IDE c’est pas super friendly

Bref après on peut travailler juste avec des Google docs ou écrire les specs seulement dans les tickets mais là on perd toute recherche et recoupement que l’on aimerait faire.

Du coup il reste quel piste ? Le wiki ? Pas pratique pour faire de la relecture en équipe, on doit attendre que le copain ait fini d’éditer la page pour faire ses modifications.. bref pas top.

La solution qui a bien fonctionné pour moi et les équipes où j’ai travaillé dernièrement est la suivante :

  • Un dépôt dédié à la documentation. Comme ça on ne se pose plus la question du “où”
  • On peut fonctionner en pull request ou directement sur master si on édite par bitbucket/github, soyons cool avec tout le monde
  • Installer mkdocs et faire en sorte de déployer ce projet (automatiser le git pull && mkdocs build devrait pas être un souci pour vous), comme ça on a un joli site avec recherche intégré
  • Avec ‘mkdocs serve’ on voit le site en live et il se reload tout seul quand on écrit.
  • Et installer un thème comme mkdocs material et là on se dit que ça a de la gueule

Et vous quel stratégie marche bien ?

About: Oni

Développeur depuis maintenant plus de 10 ans, j'ai tenu plusieurs blogs techniques (pour moi, pour les sociétés qui m'employait), et comme je le faisait en mode "side project", rien n’avançait vraiment. Je suis maintenant Freelance, et j'ai enfin la liberté d'organiser mon temps comme je le souhaite, du coup j'en rouvre un. PS: Voici mon CV ;p


Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.