Skip to content

Latest commit

 

History

History
223 lines (171 loc) · 10.7 KB

documentation.md

File metadata and controls

223 lines (171 loc) · 10.7 KB

La documentation

Considérations générales

📌 La documentation est un processus complexe et contraignant qui peut être polymorphe et soumis à différentes contraintes.

Les objectifs

La documentation doit :

  • transmettre l'information utile
    • de manière asynchrone
    • qui doit être partagée
    • sinon l'oral suffit.
  • pour un produit, faciliter sa prise en main et favoriser son adoption.

Les principaux enjeux

La documentation devrait :

  • se limiter à l'essentiel, le strict utile.
  • éviter les duplications.
  • être la plus maintenable possible.
  • être synchronisée avec le code.

Les principales problématiques

La documentation :

  • est souvent absente.
  • est souvent obsolète.
  • est souvent non pertinente.
  • est souvent non motivante à lire et surtout à écrire.
  • vérifie souvent la Loi de "LeBlanc" : plus tard = jamais.

Les contraintes à prendre en compte

  • La durée de validité des informations.
  • La pertinence des informations.
  • La population ciblée (type, niveau de connaissance, ...).

Les différents types

  • La documentation technique
    • Architecture logicielle
    • Architecture technique
    • Conception technique
    • Guide du développeur
    • Normes de développement
    • Guide de bonnes pratiques
    • FAQ (interne ou externe)
    • ADR
  • La documentation fonctionnelle
    • Guides ou manuels utilisateurs (externe)
    • Spécifications, expressions des besoins
    • FAQ (interne ou externe)

Les différents formats

  • Pour la rédaction :
    • Propriétaire (Word, PPT, Confluence)
    • Markdown
    • Asciidoc
    • Texte
  • Pour l'export :
    • PDF
    • HTML

La documentation implicite

Il existe différentes autres formes de documentations qui peuvent fournir des éléments complémentaires ou précisions dans le cadre de la compréhension d'un sujet. On pourra noter par exemple :

  • Les commentaires (attention peuvent rapidement devenir obsolètes ou erronés).
  • La Javadoc.
  • Swagger / OpenAPI (documentation d'API).
  • Les tests unitaires.
  • Les scénarios de tests (Gerkhin, ...).
  • Les changelog ou Release Notes.
  • L'historique des commits Git.
  • Les discussions des issues GitLab / GitHub.
  • Les discussions de Merge Requests GitLab / Pull Requests GitHub.

Quelques bonnes pratiques

Ne documenter que l'essentiel

📌 La documentation prend du temps, il est donc important de se concentrer sur ce qui apporte de la valeur.

  • Valider préalablement en équipe les besoins ou manques.
  • Ne pas dupliquer, ré-écrire ou paraphraser une documentation existante : référencer la documentation officielle et ajouter vos éventuelles spécificités ou vos remarques.
  • Considérer l'écriture des ADR (Architectural Decision Records) :
    • C'est le journal de toutes les décisions architecturales prises durant la vie du projet.
    • Ce journal permet de connaître l'historique et surtout les justifications des grandes décisions techniques prises au cours de la vie du projet.
    • Il devient particulièrement utile quand les personnes qui ont prises les décisions ne sont plus la et pour les nouveaux arrivants.
    • Ce journal fait partie intégrante du dépôt de sources, le format Markdown est donc le plus adapté, sa structure doit être standardisée.

Assurer la maintenabilité

📌 Il n'y a rien de pire qu'une documentation erronée ou obsolète. La documentation pour être utile doit être fiable, à jour et vivante et donc elle doit pouvoir être facilement mise à jour.

  • Choisir l'outil validé par l'équipe qui va maintenir la documentation (qui n'est pas forcément celle qui va la lire ou la valider).
  • Éviter les gros pavés, les gros fichiers, favoriser une documentation modulaire, bien découpée.
  • Favoriser les pratiques de type Documentation as Code :
    • Gestion des versions et des retours en arrière.
    • Pratique de revues collectives.
    • Soumissions de Pull/Merge Request.
  • Limiter le copier-coller (blocs de code, ...) qui peut vite engendrer de l'obsolèscence et donc de la maintenance.

Améliorer la lisibilité

📌 Personne n'aime lire ou maintenir de la documentation, il faut donc la rendre la plus claire et lisible possible.

  • Les titres doivent être explicites et clairs.
  • Éviter les blocs trop longs, essayer d'être synthétique.
  • Rester concis et pertinent, éviter le superflus et le trop littéraire.
  • Soigner l'orthographe et les accords (utiliser des spell checker dans vos outils et IDE) et la ponctuation.
  • Lever les ambiguïtés :
    • Écrire au présent et à la voix active.
    • Éviter les synonymes, utiliser toujours le même terme pour désigner la même chose.
  • Garder le même style et les mêmes normes tout au long de la documentation :
    • Polices de caractères.
    • Format des titres et sous-titres.
    • Format des sections (blocs de code, ...).
    • Format des listes à puces.
  • Ne pas négliger l'ajout de schémas ou d'images, ou d'extraits de code source :
    • Rend la documentation plus facile à lire, plus compréhensible.
    • Attire le regard, attise la curiosité.
    • Attention néanmoins aux copie d'écrans et blocs de code qui peuvent vite devenir obsolètes.

Impliquer toute l'équipe

📌 La documentation est l'effort de toute l'équipe. Il est important que toute l'équipe y soit impliquée.

  • C'est un processus collaboratif : plusieurs cerveaux valent mieux qu'un.
  • C'est un processus itératif : on a rarement bon du 1er coup, tout seul.
  • La documentation doit être revue et validée par l'équipe.

Utilisez l'outil de documentation approprié

📌 Le choix du bon outil de rédaction peut permettre de gagner du temps ainsi qu'en qualité sur le résultat produit.

On choisira un outil :

  • adapté au type de documentation :
    • des graphiques, schémas, diagrammes : draw.io, ...
    • une documentation fonctionnelle : page Confluence, ...
    • une documentation technique : outil et format à valider par l'équipe de développement.
  • adapté à la population ciblée :
    • Développeurs du projet : Markdown intégré au dépôt de sources.
    • Équipe projet : espace Confluence, ...
    • Utilisateurs du produit : directement intégrée au produit.

Synthèse : pourquoi documenter son projet ?

  • pour soi-même pour pouvoir s'y référer dans 6 moins ou plus.
  • pour les autres développeurs ou ceux qui arriveront prochainement sur le projet.
  • comme pour les tests, impose de devoir reposer les choses, expliquer les concepts, les choix, il peut donc en résulter une remsie en question ou la découverte de problèmes non identifiés initialement.

Annexes

Annexe 1 : quelques outils de génération de diagrammes

  • PlantUML : génération de diagrammes sous forme d'images à partir d'une syntaxe textuelle.
  • Mermaid : génération de diagrammes à partir d'une syntaxe textuelle, directement insérable dans des fichiers au format Markdown.
  • Graphviz - Graph Visualization Softwar : génération de diagrammes à partir d'une syntaxe textuelle, dot syntax par exemple.
  • Draw.io : outil graphique gratuit de génération de diagrammes avec possibilité d'export dans différents formats.
  • MagicDraw : outil payant.
  • tldraw : outil graphique simple et gratuit de génération de diagrammes.
  • Excalidraw : outil graphique simple et gratuit de génération de diagrammes.

Annexe 2 : quelques outils de génération de sites

Annexe 3 : outils conseillés pour Markdown

  • MarkText : Simple and Elegant Markdown Editor : Focused on speed and usability
  • Microsoft Visual Studio Code
    • Extension MarkdownLint davidanson.vscode-markdownlint Markdown linting and style checking for Visual Studio Code
    • Extension Markdown Emoji bierner.markdown-emoji Adds emoji syntax support to VS Code's built-in markdown preview
    • Extension Markdown Preview Github Styling bierner.markdown-preview-github-styles Changes VS Code's built-in markdown preview to match Github's style
    • Extension Code Spell Checkerstreetsidesoftware.code-spell-checker Spelling checker for source code
    • Extension French - Code Spell Checker streetsidesoftware.code-spell-checker-french French dictionary extension for VS Code

Annexe 4 : outils conseillés pour AsciiDoc

Annexe 5 : conseils pour la rédaction des Javadocs

  • Documenter toutes les classes et méthodes publiques ou protected.
  • Préciser les comportements :
    • Préciser si une méthode peut engendrer un effet de bord (modification d'un élément fourni en paramètre).
    • Préciser si pour un paramètre de méthode la valeur null est acceptée.
    • Préciser si une méthode peut retourner null.
    • Dans le cas d'une méthode qui retourne une collection, préciser si celle-ci est mutable ou non.
    • Préciser si une classe est Thread-Safe ou non.
  • Ne pas surcharger inutilement la javadoc d'une méthode si elle n'apporte rien de plus que celle de la méthode parente.
  • Syntaxe :
    • Utiliser les éléments de syntaxe évolués : {@link Classe#methode(ParamType)}, {@code exemple("xxx");}, {@value}, ...
    • Utiliser les tags HTML simples et non les tags XHTML. Exemple <br> au lieu de <br/>.
    • Documenter les types génériques utilisés dans une méthode : @param <T> le type.
    • Préciser depuis quand via @since X.y.Z.
    • Préciser la version courante via @version (classes, interfaces, enums uniquement).
  • Compléter via @deprecated raison si une annotation @Deprecated est utilisée sur un élément.
  • Générer et valider les javadocs simplement en exécutant via Maven la commande mvn javadoc:javadoc, corriger les avertissements et erreurs remontées.

Annexe 6 : citations

  • Documentation is a love letter that you write to your future self. - Damian Conway
  • Don’t document the problem, fix it. - Atli Björgvin Oddsson