Pourquoi faire une documentation (avec quelques idées de contenu)

Vous êtes chargé de nourrir une équipe de 5 personnes en préparant une omelette aux champignons. Vous devez aller cueillir les-dits champignons en forêt, il vous en faut quelques kilos et vous n’y connaissez rien en terme de comestibilité (ni toxicité). Prendriez-vous un livre sur le sujet ?

Il est fréquent de constater que dans le milieu professionnel on recommande de demander aux personnes qui s’y connaissent où de trouver par soi même. On vous demande donc de partir en forêt avec une équipe, voir tout le village, pour savoir quel champignon cueillir et ceux à éviter. Si ils n’ont pas la réponse il suffira de faire goûter un extrait à quelqu’un pour en déterminer la nocivité (modification de code à l’aveugle).

La documentation d’un projet est souvent négligée au point de devoir en référer aux personnes ayant contribué au code ou, quand elles sont absente/parties, comprendre par vous même. Ce comportement peut entrainer un mauvais usage des fonctions existantes ou la création de régression. Pourtant elle est tout aussi importante que les tests sur un projet logiciel et même si on la comprend dans le bagage qualité, rangé au niveau facultatif faute de temps, elle est d’un avis plus personnel, inhérente au développement.

Si le code est explicite, lisible, avec des conventions respectées elle ne se résumera principalement qu’à la définition fonctionnelle du projet. Mais dans des projets plus complexes et quand les équipes tournent souvent il est bon de débuter une bonne documentation. Le respect de certains standards de développement (architecture n-tiers, framework, convention de nommage externes) permet bien souvent de ne pas avoir a expliquer par soi même la structure du code.

Avantages

Une bonne documentation permettra un gain d’autonomie et de vitesse d’apprentissage des nouveaux arrivants. L’équipe de développement sera plus polyvalente sur les domaines qu’elle peut traiter et il y aura moins de flou sur le fonctionnement du logiciel.

Enfin elle peut permettre d’améliorer la communication entre différents services (développeur et commercial par exemple). Car il ne faut pas oublier que si elle est souvent à destination de l’équipe technique (de développement) elle peut aussi permettre l’information de services transverses et d’éviter cette charge au chef de projet: « Quelles sont les fonctionnalités de la dernière version? », « Quand la version 2.1.3 sera disponible? » etc …

Format

La documentation n’est pas forcément mono-support, on peut la retrouver dispersée et sous plusieurs formats (le fonctionnel dans un wiki, la roadmap dans un outil spécial (de type Redmine), les informations de test dans un fichier de bootstrap, les check-list au format papier etc …

Certains outils permettent de générer une documentation à partir de l’existant (change-log, dictionnaire de données…) ne les négligez jamais sous prétexte qu’il faut mieux avoir la documentation en un seul et même endroit (sur un wiki par exemple). Une documentation séparée dont la mise à jour peut être automatique (via de l’intégration continue) est toujours meilleure qu’une documentation simple à trouver mais difficilement modifiable. Rien de plus terrible qu’une documentation qui n’est pas à jour.

Limitations

La documentation de type Wiki ne remplace pas les commentaires au sein du code. Elle n’est pas la pour expliquer chaque fonction mais apporter d’autres éléments de compréhension.

Pour un nouveau développeur, elle ne remplace pas l’explication en binôme, elle est là pour poser les bases, mettre les ressources à disposition et permettre au « formateur » de ne rien oublier, mais l’explication commentée du code reste indispensable.

Contenu

Voici quelques parties de cette documentation qui, aux yeux de ma courte expérience, peuvent être utiles. Toutes ne le sont pas forcément (et la liste n’est pas exhaustive). Il est important de voir avec l’équipe quelle information devrait être consignée car dure à retrouver au sein du code.

Note: je ne parlerais pas ici d’outils de gestion comme l’annuaire des employés et de leurs compétences, du planning de disponibilité des développeurs, des informations de connexions (mot de passe), de l’organigramme. Ces informations peuvent cependant être citées dans le plan de documentation.

Un plan de la documentation : c’est une « meta-documentation » qui permet de savoir où chercher la documentation si celle ci est éparse. Par exemple elle donnera le chemin du change-log ou des logs, celui du dictionnaire de données, du plan d’architecture etc … Ce plan est d’autant plus nécessaire si la documentation est repartie à plusieurs endroits (lecteurs réseaux différents). Idéalement il doit tenir sur une feuille A4 et doit pouvoir être imprimé et rapidement visible par les équipes.

La définition des termes métiers et de leur règles: dans le domaine bancaire par exemple on pourrait définir le BAN/BIC et ses caractéristiques (longueur, caractères autorisés…). Généralement le domaine métier est plus complexe à appréhender que le code lui même, surtout pour un débutant.

Un plan architecture matérielle: serveurs, configurations logicielles, plateformes (dev/test/pré-production). Plutôt rapide à réaliser et d’autant plus nécessaire qu’il permet de rassembler les adresses IP pour un accès à distance rapide. Si un outil de provisionning (Ansible, Puppet …) existe alors on peut y lister les commandes les plus utiles. Si la pratique devOps n’est pas appliquée et que les personnes ne doivent pas toucher aux plateformes qui ne leur sont pas propres, un récapitulatif de chaque configuration peut aider à la résolution d’un conflit : par exemple la date de la plateforme dev est en Europe/Paris et la prod est en UTC.

Architecture et structure du code: si le framework est maison et basé sur une architecture particulière il est intéressant de définir le chemin d’exécution: point entrée, exemple de cheminement des informations, couche chargée de la validation des données, de la persistance, etc …

Conventions de codages, bonnes pratiques: Si un framework est utilisé lister les exceptions vis a vis des bonnes pratiques recommandées pour ce framework: cela pourra être utile lors d’un changement de version de l’outil.

Dictionnaire de données de la base de données: avec par exemple les valeurs possibles dans les colonnes. On peut aussi lister les règles qui existent entre deux colonnes (valeur d’une colonne qui dépend de la valeur d’une autre colonne) mais évitez de lister l’ensemble des colonnes. Certains outils existent pour créer cette documentation (tables, colonnes, contraintes, description des objets) en se basant sur les commentaires du SGBD.

Il peut être utile de rassembler les documents des méthodes agiles: compte-rendu de rétrospectives, axes d’amélioration, correspondance sprint/version/fonctionnalités …

Procédures et check-list: étapes à suivre lors du déploiement, de la création de branches, de la modification de code spécifique, des code-review et check-list des bonnes pratiques concernant la sécurité par exemple. Un document synthétique à avoir sous les yeux permet d’éviter les oublis liés à la routine.

Change-log des versions: idéalement dans le logiciel de suivi (de type Redmine/Trac) ou dans les sources (fichier) : nécessaire pour connaitre rapidement les changement et fonctionnalités majeurs de chaque version. Il peut être utile pour le service commercial.

Roadmap: (proche du point précédent) avec les dates importantes (mises à jour, déploiements, réunions …). Il peut s’agir d’un planning partagé avec les équipes.

Jeux de tests: en résumé « Quel utilisateur possède quel droit et quelle configuration sur quelle plateforme? « . Permet d’éviter d’avoir à créer des utilisateurs pour tester un comportement anormal (bug) sur une plateforme donnée.

Dépendances au projet: logiciels et librairies utilisées, avec version et documentation pour éviter la dette technique (les mises à jour de sécurité en premier lieu). Ce n’est pas utile si le projet utilise un outil de gestion de dépendance (composer, nugget …).

Documentations externes des outils: page qui liste simplement un lien vers un bon tutoriel d’initiation à l’outil (Git, framework…) surtout pour des outils SAAS (NewRelic, Github …) vu que le recours à ces services est de plus en plus fréquent. Idéalement les développeurs connaissent déjà tous ces outils mais au besoin cela peut être utile pour des stagiaires ou des profils non techniques (direction qui vous demande de justifier l’utilisation de tel outil SAAS) de connaitre rapidement le fonctionnement et les possibilités.

Ressources et liste des liens utiles: sites traitant de la technologie ou des méthodes utilisées (agiles) ou n’importe quelle ressource utile pour la veille.

Snippets: fragments de code partagé entre développeurs comme les principales commandes Git (ou justement celles qui peuvent être complexes) ou les commandes plus génériques permettant par exemple de lister les actions GruntJS existantes etc …

Boite à idées: tout projet à ce genre de problèmes qui se résout généralement avec un outil/ une pratique (par exemple le provisionning de serveurs). L’avantage d’avoir une page dédiée aux idées est de notifier les problèmes/solutions utilisables sur le projet pour qu’elles puissent être vues et réfléchies avant une rétrospective de sprint où l’on pourrait en parler. On déporte ainsi du temps de recherche et de débat en dehors de la rétrospective. De mon point de vue le format idéal d’une boite à idée est une application web de mind-mapping.

Voila j’espère que cette histoire de champignons vous aura convaincu du besoin de documentation et que cette liste pourra vous aider à produire de beaux documents que tout nouvel arrivant sera ravi de lire. La documentation est un moyen simple de suivre l’évolution du logiciel, si elle devient complexe à écrire alors elle peut donner l’alerte sur une trop forte complexité du projet (nombreux cas spécifiques, hacks) et donc des problèmes de maintenance et d’évolution.

N’hésitez pas à partager vos idées, vos questions, vos retours d’expériences ou des exemples d’outils qui manquent à cet article. Merci

Auteur de l’image: https://www.flickr.com/photos/marufish/

Publicités

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s