Comment écrire un fichier README utile pour votre prochain projet | de Ashley Peacock | janvier 2023

Permettez à n’importe quel ingénieur de se mettre au courant de votre projet rapidement et facilement

Il y a de fortes chances que vous ayez déjà écrit ou contribué à un fichier README. Il devrait en exister un dans chaque référentiel et couvrir les informations essentielles sur ce référentiel.

Lors de la rédaction du README, il peut être difficile de savoir quoi inclure. Au fil des ans, j’ai écrit de nombreux fichiers README pour de nombreux référentiels. Dans cet article, je vais décrire les incontournables pour tout README.

Commençons par jeter un coup d’œil rapide sur ce qu’est un README, pour ceux qui ne sont pas familiers. Si vous êtes déjà familier, n’hésitez pas à passer à la rubrique suivante !

En bref, vous pouvez considérer le README comme la documentation principale de tout référentiel. Ce devrait être le premier endroit où tout le monde va pour lire ce que fait votre projet, comment il le fait et comment vous pouvez démarrer avec ce référentiel.

Il est généralement écrit en Markdown, un langage de balisage simple pour écrire des documents texte. Le README n’a pas besoin d’être flashy. Je préfère un README concis contenant les informations absolument indispensables, avec tout ce qui est supplémentaire stocké dans un autre fichier Markdown et lié à partir du README.

Maintenant que nous comprenons ce qu’est un README, regardons comment nous pouvons en écrire un bon, étape par étape.

Comme vous vous en doutez, nous commençons par présenter le projet à un niveau élevé. Cela devrait être en grande partie non technique, car les README ne sont pas seulement lus par les ingénieurs mais aussi par les chefs de projet, par exemple.

J’inclurais également ses principales responsabilités. De cette façon, n’importe qui comprend immédiatement la portée de ce référentiel. Ils pourraient chercher où apporter un changement, et une introduction concise leur répondra rapidement s’il s’agit d’un endroit potentiel pour eux d’effectuer leur changement sans parcourir le code.

Si votre entreprise utilise Dossiers de décision d’architecture (ADR), c’est l’endroit idéal pour établir un lien vers l’ADR qui explique la raison d’être de la création de ce référentiel. Si vous n’utilisez pas d’ADR (je vous le recommande vivement !), un paragraphe fournissant cette justification suffirait.

Vous pouvez écrire aussi peu ou autant que vous le souhaitez, dans la limite du raisonnable. En règle générale, je vise un paragraphe ou deux.

Avec la popularité croissante du Domain-Driven Design (DDD), de nombreuses entreprises ont maintenant modèles de domaine facilement à leur disposition. Vous ne pouvez pas, et ce n’est pas grave. Vous pouvez toujours inclure une section sur votre domaine ; ce ne sera tout simplement pas aussi détaillé. Si ce référentiel implémente une partie d’un modèle de domaine, assurez-vous de l’inclure, de préférence sous forme de diagramme.

L’inclusion d’informations sur votre domaine permet à quiconque consulte le README de comprendre les entités clés en jeu. En outre, vous devez décrire les entités clés et leurs responsabilités à côté du diagramme. Si votre domaine est assez grand et qu’il y a beaucoup d’entités, je vous recommande d’inclure le diagramme dans le README, de déplacer les descriptions des entités dans un fichier Markdown séparé et de le lier à partir de la section du modèle de domaine.

Un moyen simple d’intégrer un modèle de domaine dans votre README consiste à utiliser Sirène. Il vous permet de créer des diagrammes en utilisant une syntaxe de type Markdown, et si vous utilisez GitHub ou GitLab (et quelques autres), il vous permettra d’intégrer ce balisage dans un fichier Markdown, et tout le monde verra le diagramme rendu comme une image lorsqu’il est visionné !

Si vous n’avez pas de modèle de domaine formel, je décrirais les entités ou modèles clés de votre système. Ce sont les classes qui rendent votre système unique et que votre système est responsable de la gestion. Par exemple, dans un système qui s’occupe des données client, une entité clé serait probablement Customer .

Une fois l’introduction terminée, nous pouvons maintenant passer à la documentation de l’architecture de ce référentiel. Ce que vous documentez dépendra du type de référentiel dont il s’agit. Nous examinerons les deux plus courants : les bibliothèques et les systèmes.

Documenter l’architecture d’une bibliothèque

Si le référentiel est une bibliothèque qui construit un package (par exemple, un package Ruby Gem ou NPM), cette section sera courte. Je décrirai les décisions que vous avez prises (par exemple, nous utilisons le modèle de stratégie et un lien vers des exemples de code) et mentionnons toutes les dépendances clés (par exemple, vous utilisez la bibliothèque X pour gérer Y).

Documenter l’architecture d’un système

Si le référentiel est un système déployé indépendamment, comme une application full-stack ou une API, cette section sera un peu plus longue que celle d’une bibliothèque.

Vous devez viser à donner une vue de haut niveau de l’architecture du système dans le README afin que toute personne parcourant le README puisse comprendre en un coup d’œil le fonctionnement de votre système.

Pour cette raison, je suis un grand fan de l’utilisation du Modèle C4 pour documenter les architectures système. L’article lié est une excellente introduction au modèle C4. Je vous recommande de le lire après cela et de mettre le diagramme de contexte du système dans votre README.

En bref, le diagramme de contexte du système décrit les systèmes qui dépendent de votre système, ou dont votre système dépend, pour fonctionner. C’est délibérément non technique, et les relations sont décrites en termes de fonction plutôt que de protocoles. Ci-dessus, vous pouvez voir un exemple de diagramme de contexte système pour un service de référencement.

En remarque, je recommanderais également de créer le diagramme de conteneur à partir du modèle C4, mais je l’inclurais dans un fichier Markdown séparé et le lierais à partir de la section architecture du README. Dans ce fichier séparé, avec le diagramme du conteneur C4, vous pouvez en dire plus sur l’architecture.

Si vous les créez, Mermaid, encore une fois, peut être très utile pour créer les diagrammes du modèle C4. j’ai récemment a écrit sur le modèle C4 et comment vous pouvez les créer en utilisant Mermaid, donc je vous recommande de lire cela après cet article si vous êtes intéressé.

Une autre chose utile à inclure dans cette section est toute autre documentation technique, telle que les schémas d’API.

La partie la plus importante de tout fichier README est probablement une section souvent appelée runbook. C’est un terme générique pour un ensemble d’instructions ou de procédures qui doivent être suivies pour atteindre un ensemble de résultats souhaités.

Chaque dépôt doit avoir au moins deux entrées dans le runbook :

1. Comment installer et exécuter ce référentiel. Qu’il s’agisse d’une bibliothèque ou d’un service, il y aura toujours des étapes nécessaires avant que le développement puisse commencer.
2. Comment exécuter la suite de tests pour ce référentiel. Votre référentiel contient des tests, n’est-ce pas ? Espérons-le, et avec une pléthore d’options pour exécuter une suite de tests (qui peuvent varier au sein d’une organisation) ; il est préférable de documenter explicitement comment exécuter la suite de tests.

Ce n’est pas tout, cependant. Il peut y avoir des processus spécifiques à votre référentiel que vous pouvez appeler ici. Gardez à l’esprit qu’un README n’est pas un document statique écrit une seule fois, donc si vous remarquez qu’un processus est exécuté à plusieurs reprises, ajoutez-le au runbook !

Un exemple classique dans la plupart des projets sur lesquels je travaille dans mon entreprise actuelle est la lecture et la mise à jour de secrets. Nous stockons des secrets dans AWSKMSdes instructions spécifiques sont donc nécessaires pour déchiffrer et chiffrer les secrets dans chaque référentiel.

Comme pour les sections ci-dessus, si votre runbook est assez long, incluez les éléments clés (par exemple, installez, exécutez et testez) dans le README, et déplacez le reste dans un fichier séparé lié au README.

Pour la plupart des référentiels, vous aurez une stratégie de déploiement lorsque les fusions se produiront.

Cela peut être complètement automatisé, ou complètement manuel, ou quelque part entre les deux. Quoi qu’il en soit, c’est la section où vous informez toute personne lisant comment déployer ses modifications.

J’espère que c’est aussi simple que de lancer une demande d’extraction et de la fusionner, et un Pipeline CI/CD automatise tout après cela. S’il y a des étapes manuelles, assurez-vous de les écrire, afin que tout le monde soit au courant.

La dernière section que j’aime inclure est une section FAQ, y compris tous les « gotchas » du référentiel. Cette section est souvent omise, surtout si le système est tout neuf.

Cependant, vous verrez probablement des collègues poser des questions sur votre référentiel au fil du temps. Certains des plus courants sont « Comment puis-je faire X ? » ou « Pourquoi Y continue-t-il à se produire ? ».

Plutôt que de répondre à ces messages encore et encore, pensez à les inclure dans cette section. Espérons que les gens consulteront cette section avant de demander de l’aide au fil du temps. Au pire, vous pouvez leur demander de vérifier cette section plutôt que de régurgiter votre réponse à chaque fois.

De la même manière qu’une FAQ, il y a des pièges. Ce sont comme les petits gremlins du système et peuvent souvent être formulés comme une FAQ. Bien que je recommande toujours d’essayer de résoudre le problème sous-jacent, la meilleure chose à faire est de reconnaître le problème et de fournir une solution de contournement.

Encore une fois, si cette section devient trop volumineuse avec le temps, vous pouvez la déplacer vers un fichier Markdown séparé et le lier à partir du README.

Cela complète mon guide étape par étape pour créer un fichier README utile. Une fois que j’ai terminé avec le README, j’aime aussi créer une table des matières en haut, juste en dessous de l’introduction. Cela permet à quiconque de voir quelles sections sont incluses dans le README et de passer rapidement à celle qui l’intéresse.

Comme mentionné tout au long de l’article, le README est un document vivant. Il devrait évoluer, qu’il s’agisse de mettre à jour la documentation de l’architecture ou d’ajouter une nouvelle FAQ.

Lorsqu’il est bien fait, un README peut vous faire gagner du temps, à vous et à vos collègues, pour répondre aux questions d’assistance auxquelles un bon README peut souvent répondre !

Avez-vous des sections incontournables dans vos README que j’ai manquées ?