Rédiger un README de projet efficace

La première (et parfois seule) chose que quelqu'un lira

Rédiger un README de projet efficace

Structurer le README à la racine de votre repo pour qu'il donne, en 2 minutes de lecture, tout ce qu'il faut savoir avant de creuser.

Durée :
Difficulté :

Pré-requis :

Logiciels :

Machines/Outils :

Documentation réalisée à 65% 65
Créée par :  Adrien Bracq

Pourquoi le README compte autant

Le fichier README.md à la racine de votre repo s’affiche automatiquement sur la page GitHub du projet — c’est souvent la toute première chose que lira un jury, un encadrant, ou une prochaine équipe, avant même d’ouvrir votre site de documentation. Voir aussi Rendre son projet transmissible pour le principe général.

  Le test des 30 secondes

Montrez votre README à quelqu’un qui n’a jamais vu votre projet, chronomètre en main. En 30 secondes, il doit pouvoir dire ce que fait le projet et s’il l’intéresse. Si ce n’est pas le cas, ce n’est pas un problème de rédaction, c’est un problème de structure — voir plus bas.

Ce que chaque section doit faire, précisément

Un bon README répond à quatre questions, dans cet ordre — chacune a un rôle précis, pas juste “un peu plus d’info” :

  • Titre + une phrase : le nom du projet (pas une description en guise de titre), puis une seule phrase qui dit ce que ça fait, pas comment vous l’avez fait. “Robot de tri de déchets pour le Forum des Sciences”, pas “Projet réalisé dans le cadre de l’UE Méthodologie”.
  • Documentation complète : un lien, pas un résumé. Le README pointe vers le site docs/, il ne le duplique pas — voir juste en dessous.
  • Limites connues : ce qui ne marche pas encore, ou pas parfaitement — voir Rendre son projet transmissible pour pourquoi c’est important de le dire.
  • Équipe et licence : qui a fait le projet (et comment vous recontacter), et sous quelle licence il est réutilisable — voir Comprendre la propriété intellectuelle de son projet.
  Pas de « comment le lancer » dans le README

Comment faire fonctionner ou reproduire votre projet a sa place dans le site de documentation (docs/), pas dans le README — c’est justement le rôle de la documentation complète. Le README pointe vers elle, il ne refait pas le travail.

Une image vaut mille lignes de texte

Une photo ou un GIF de votre prototype en action, juste après le titre, convainc plus vite que n’importe quel paragraphe. Prenez-la au moment où vous avez déjà un résultat visuel — voir Documenter au fil de l’eau — pas en dernière minute avant le rendu.

![Le robot de tri en fonctionnement](docs/images/robot-en-action.gif)

Vague vs structuré : un exemple

# Projet de robot de tri

Projet réalisé au MakerSpace pour le Forum des Sciences.

# Robot de tri de déchets

![Le robot en action](docs/images/robot-en-action.gif)

Robot capable de trier 3 catégories de déchets (plastique, verre, métal),
conçu pour une démonstration pédagogique au Forum des Sciences d'Amiens.

## Documentation complète

Voir le [site de documentation](https://votre-projet.github.io) pour le
détail de la conception, des choix techniques et des tests.

## Limites connues

- Taux de tri correct : ~80% (voir les résultats de tests détaillés)
- Non testé sous forte luminosité directe

## Équipe

Projet réalisé par [Prénom Nom](mailto:...), [Prénom Nom](mailto:...) —
MakerSpace UniLaSalle Amiens, 2026.

## Licence

MIT — voir [LICENSE](LICENSE)

Un gabarit à copier

Copier le gabarit (Markdown) 
# Nom du projet

![Le projet en action](docs/images/apercu.gif)

Une phrase de description : ce que fait le projet, pour qui.

## Documentation complète

Voir le [site de documentation](...).

## Limites connues

- ...

## Équipe

Projet réalisé par [Prénom Nom](mailto:...), [Prénom Nom](mailto:...)

## Licence

... — voir [LICENSE](LICENSE)
  Un README n'est pas la documentation complète

Il pointe vers elle, il ne la remplace pas. Si votre README dépasse une page d’écran, une bonne partie de son contenu devrait probablement vivre dans docs/ à la place.

Un petit plus optionnel : les badges

Les petites pastilles colorées en haut de beaucoup de README GitHub (licence, statut de build…) se génèrent gratuitement sur shields.io, sans rien installer. Un badge de licence, par exemple :

![License: MIT](https://img.shields.io/badge/license-MIT-green)

Ce n’est que de la décoration utile — ne passez pas de temps dessus si le reste du README n’est pas déjà solide.

Erreurs fréquentes

Erreur Pourquoi ça pose problème À faire à la place
Le titre est une phrase descriptive longue Ne se lit pas comme un nom de projet Un nom court, la description juste en dessous
Copier toute la doc technique dans le README Devient illisible, jamais à jour sur les deux fronts Un lien vers docs/, rien de plus
Aucune limite mentionnée Donne une fausse impression de projet fini Voir le README structuré ci-dessus
Écrit une seule fois, jamais relu Devient obsolète dès que le projet évolue Relire à chaque jalon important — voir Gérer le temps et les jalons

Exercice

Ouvrez le README.md de votre repo (créé automatiquement depuis le template) et réécrivez-le en suivant la structure ci-dessus, avec le vrai contenu de votre projet. Faites-le relire par quelqu’un d’extérieur à l’équipe avec le test des 30 secondes.

Contents