Rédigez une documentation qui fonctionne réellement pour votre communauté

Établir une bonne documentation peut être difficile, mais c'est essentiel pour une communication efficace. Suivez ce cadre pour rédiger et partager de la documentation avec les bonnes personnes.

Qu’est-ce qui distingue les projets réussis et durables de ceux qui ont disparu dans le vide ? Spoiler : c'est la communauté. La communauté est le moteur d’un projet open source, et la documentation est l’un des éléments fondamentaux de la construction d’une communauté. En d’autres termes, la documentation n’est pas seulement une question de documentation.

Cependant, établir une bonne documentation peut être difficile. Les utilisateurs ne lisent pas la documentation parce qu'elle n'est pas pratique, qu'elle devient très vite obsolète, qu'il y en a trop ou pas assez.

L'équipe de développement n'écrit pas de documentation à cause du piège « c'est évident pour moi, donc c'est évident pour tout le monde ». Ils n'écrivent pas parce qu'ils sont trop occupés à faire exister le projet. Les choses évoluent trop vite, ou pas assez vite.

Mais une bonne documentation reste le meilleur outil de communication pour les groupes et les projets. Cela est d’autant plus vrai que les projets ont tendance à prendre de l’ampleur avec le temps.

La documentation peut être une source unique de vérité au sein d’un groupe ou d’une entreprise.  Ceci est important pour coordonner les personnes vers un objectif commun et préserver les connaissances à mesure que les gens progressent vers différents projets.

Alors, comment rédiger une documentation appropriée pour un projet et la partager avec les bonnes personnes ?

Qu’est-ce qu’une documentation communautaire réussie ?

Pour réussir à rédiger de la documentation dans votre communauté :

• Organisez votre routine

• Soyez clair et direct

• Être flexible, apporter des changements à la routine en fonction d'une situation précise

• Effectuer le contrôle de version

(Olga Merkoulova, CC BY-SA 4.0)

Être flexible ne signifie pas être chaotique. De nombreux projets ont réussi simplement parce qu’ils étaient bien organisés.

James Clear (auteur de Atomic Habits) a écrit : "Vous n'atteignez pas le niveau de vos objectifs. Vous tombez au niveau de vos systèmes." Assurez-vous d'organiser le processus de manière à ce que le niveau soit suffisamment élevé pour réussir.

Concevoir le processus

La documentation est un projet. Pensez à écrire des documents comme à écrire du code. En fait, la documentation peut être un produit très utile.

Cela signifie que vous pouvez utiliser les mêmes processus que dans le développement de logiciels : analyse, capture des exigences, conception, mise en œuvre et maintenance. Faites de la documentation l’un de vos processus.

Pensez-y sous différents angles lors de la conception du processus. Toute documentation n’est pas adaptée à tout le monde.

La plupart des utilisateurs n'ont besoin que d'une vue d'ensemble de haut niveau d'un projet, tandis que la documentation de l'API est probablement mieux réservée aux développeurs ou aux utilisateurs avancés.

Les développeurs ont besoin de documentation sur les bibliothèques et les fonctions. Les utilisateurs sont mieux servis par des exemples de cas d'utilisation, des guides étape par étape et un aperçu architectural de la façon dont un projet s'intègre aux autres logiciels qu'ils utilisent.

(Olga Merkoulova, CC BY-SA 4.0)

En fin de compte, avant de créer un processus, vous devez déterminer ce dont vous avez besoin :

• Groupes de discussion : ils incluent les développeurs, les intégrateurs, les administrateurs, les utilisateurs, les ventes, les opérations et les dirigeants.

• Niveau d'expertise : gardez à l'esprit les utilisateurs débutants, intermédiaires et avancés.

• Niveau de détail : il y a de la place pour une vue d'ensemble de haut niveau ainsi que pour des détails techniques, alors réfléchissez à la manière dont vous souhaitez que ceux-ci soient présentés.

• Parcours et points d'entrée : comment les gens trouvent-ils la documentation, comment ils l'utilisent

Lorsque vous réfléchissez à ces questions, cela vous aide à structurer les informations que vous souhaitez communiquer via la documentation. Il définit des mesures claires sur ce qui doit figurer dans la documentation.

Voici comment aborder la création d’un processus autour de la documentation.

Conventions de codage

Le code lui-même devrait avoir du sens. La documentation doit être exprimée à travers de bons noms de classes, de noms de fichiers, etc. Créez des normes de codage communes et élaborez un processus de codage auto-documenté en réfléchissant à :

• Conventions de dénomination des variables

• Rendre les noms compréhensibles en utilisant des schémas de dénomination de classes et de fonctions

• Évitez la nidification profonde, ou ne nichez pas du tout

• Ne vous contentez pas de copier-coller du code

• Aucune méthode longue ne doit être utilisée

• Évitez d'utiliser des nombres magiques (utilisez plutôt const)

• Utiliser des méthodes d'extraction, des variables, etc.

• Utilisez des structures de répertoires, des modules, des packages et des fichiers significatifs

Tests et ingénierie

Les tests ne concernent pas seulement la façon dont le code doit se comporter. Il s'agit également de savoir comment utiliser une API, des fonctions, des méthodes, etc. Des tests bien rédigés peuvent révéler des scénarios de base et extrêmes. Il existe même une pratique de développement pilotée par les tests qui se concentre sur la création de cas de test (scénarios étape par étape de ce qui doit être testé et comment) avant le développement du code.

Contrôle de version

Le contrôle de version, même pour votre documentation, vous aide à suivre la logique de vos modifications. Cela peut vous aider à comprendre pourquoi un changement a été effectué.

Assurez-vous que les commentaires lors des validations expliquent POURQUOI une modification a été apportée, et non QUELLE modification a été apportée.

Plus le processus de documentation est engageant, plus les gens s'y impliqueront. Ajoutez-y de la créativité et du plaisir. Vous devez penser à la lisibilité de la documentation en utilisant :

• conventions du code logiciel

• des diagrammes et des graphiques (qui sont également expliqués dans le texte)

• Les cartes mentales

• cartes conceptuelles

• infographie

• images (mettre en évidence les parties importantes)

• courtes vidéos

En utilisant différents moyens de communication, vous offrez davantage de façons d'interagir avec votre documentation. Cela peut aider à prévenir les malentendus (différentes langues, différentes significations) et les différents styles d’apprentissage.

Voici quelques outils logiciels pour créer de la documentation :

• Javadoc, Doxygen, JsDoc, etc. : de nombreux langages disposent d'outils de documentation automatisés pour aider à capturer les principales fonctionnalités du code.
• Webhooks et moteurs CI/CD : permet la publication continue de votre documentation
• Texte restructuré, Markdown, Asciidoc : les formats de fichiers et les moteurs de traitement vous aident à produire une documentation belle et utilisable à partir de fichiers texte brut.
• ReadTheDocs :  est un hôte de documentation qui peut être associé à un dépôt Git public.
• Draw.io, LibreOffice Draw, Dia : produisez des diagrammes, des graphiques, des cartes mentales, des feuilles de route, des planifications, normes et mesures
• Peek, Asciinema : utilisez les commandes pour enregistrer votre terminal
• VokoscreenNG : utiliser les clics de souris et la capture d'écran

La documentation est vitale

La documentation des processus et des protocoles est tout aussi importante que la documentation de votre projet lui-même. Plus important encore, rendez les informations sur votre projet et la création de votre projet passionnantes.

La rapidité avec laquelle on entre dans un projet et un processus, ainsi que la compréhension de comment tout fonctionne, est une caractéristique importante. Cela contribue à garantir un engagement continu. Des processus simples et une compréhension claire de ce qui doit être fait sont obtenus en construisant un « langage » au sein de l'équipe.

La documentation est conçue pour transmettre de la valeur, ce qui signifie démontrer quelque chose par des paroles et des actes. Peu importe qu'il s'agisse d'un membre de votre équipe ou d'un utilisateur de votre application.

Considérez le processus comme un continuum et utilisez des moyens de communication, des processus et de la documentation.

(Olga Merkoulova, CC BY-SA 4.0)

La documentation est un moyen de communication.