Accueil / Blog / Métier / Archives / Documenter un projet

Documenter un projet

Par Benoit Bryon — publié 02/12/2011, édité le 07/11/2015
Quelques réflexions et conseils pratiques à propos de la documentation des projets.

Pourquoi documenter ?

  • mémoire
  • transmission de savoir
  • autonomie des lecteurs
  • partage de pratiques, conventions

Un investissement

  • anticiper
    • mouvement des contributeurs
    • changement de technologie
  • produit pérenne
  • coût de changement réduit

Référence asynchrone

  • Contributeurs asynchrones peuvent utiliser la documentation comme canal de communication.

Conditions de succès

  • synchronisée avec le code
  • relue, utilisée, maintenue...
  • ... par tous ! Paternité de l'équipe au complet.
  • nécessaire, suffisante, complète
  • légère, rapide à lire, facile d'accès. Limiter l'effet "lecture en diagonale"

Conditions de succès, en pratique

  • La documentation fait partie de la definition of done (scrum)
  • La documentation est versionnée avec le code
  • Les questions d'un contributeur y trouvent un écho
  • Privilégier les références aux longues explications :
    • référencer les normes, standards et autres ressources plutôt que de les reformuler
    • Diviser les longues pages en plusieurs chapitres mieux ciblés
  • Les procédures sont scriptées :
    • faciliter la lecture
    • limiter le copier-coller
    • limiter les erreurs humaines

Documentation != référence unique

  • D'autres références plus concrètes :
    • Le produit
    • Le code
  • La documentation sert de liant
  • La documentation peut décrire des concepts :
    • processus / procédures
    • bonnes pratiques
    • motivations, vision

Pour qui documenter ?

  • équipe(s) de production
  • maintenance
  • utilisateurs
  • support
  • ...

Une documentation unique ?

  • si besoin, plusieurs documentations
  • mais au moins un point d'entrée
  • pour tous ceux qui travaillent/utilisent un même projet

Contenu

  • références, standards
  • spécificités du projet
  • procédures
  • spécifications
  • conventions, charte d'équipe

Pas contenu

  • documenté ailleurs => liens
  • spécificités d'un déploiement => configuration locale, templates
  • liste de commandes => scripts

Exemple de sommaire

  • architecture
  • backup-restore
  • configuration
  • conventions
  • documentation
  • FAQ
  • HISTORY
  • INSTALL, UPGRADE, UNINSTALL
  • LICENSE + AUTHORS
  • logging
  • monitoring
  • packaging et releasing
  • project-layout
  • scripts et commandes
  • specifications
  • testing

Architecture

  • architecture cible du projet
  • si possible, pas spécifique à un hébergement donné
  • une documentation d'architecture / déploiement du projet peut être séparée

Backup-restore

  • liste des éléments à sauvegarder
  • outils fournis pour la sauvegarde et la restauration
  • procédure d'importation de données

Configuration

  • paramètres de configuration
  • configuration par défaut
  • outils de configuration (templates)

Conventions

  • langue selon lecteurs et rédacteurs
  • conventions de codage
  • charte d'équipe

Documentation

  • outils de documentation
  • export de la documentation
  • conventions dans la documentation

HISTORY

  • historique des changemements et releases
  • lié à l'outil de versionning

Documentation VS scripts

  • INSTALL.txt c'est nécessaire. Les procédures doivent être documentées.
  • install.sh c'est mieux.
  • documentation utile pour préparer des scripts :
    • description d'une procédure dans la documentation (relevé)
    • rédaction d'un script pour la procédure (automatisation)
    • simplification de la documentation
  • documentation efficace = code est documentation + documentation succincte

Documentation VS code

  • Le code est lisible, commenté
  • Les commandes ont une documentation intégrée (man, --help...)

Outils (trêve de blabla)

ABONNEZ-VOUS À LA NEWSLETTER !