Documenter un projet
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)
- Export de la documentation :
- Génération de document, snippets :
- Doctests :
- Spécifications, BDD, ATDD :
- Sphinx + doctest + zope.browser
- Cucumber, Lettuce
- Export/import logs git/hg/svn vers HISTORY/CHANGES :
- Templates de documentation :
- drupalindustry.templates avec le template "drupal_site_docs"
- sphinx-quickstart
Étiquettes:
