Mon logiciel : mode d’emploi

Voici quelques parties de la documentation qui peuvent être utiles. Toutes ne le sont pas forcément (et la liste n’est pas exhaustive).

 

  • 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 Author-it est adapté pour un « usage 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 Author-it est utilisé, lister les exceptions et les bonnes pratiques recommandées: 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…). 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 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. 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.