Jazztinn/dontreadme

Constructeur de README pour Hackathon

Un README de hackathon a un rôle qu'un README de projet normal n'a pas : il doit gagner. Les jurés parcourent des dizaines de dépôts en quelques minutes, souvent sur un téléphone, décidant ce qui vaut même la peine d'être ouvert. Le README est la première impression du projet et souvent le seul élément qu'un juré lit avant de noter. L'objectif n'est donc pas de « documenter le code » — c'est de faire comprendre et croire rapidement un juré occupé et sceptique, et de rendre chaque affirmation trivialement vérifiable.

Cette compétence produit un README riche de type soumission, pas un README succinct. Le look-and-feel de référence se trouve dans references/readme-template.md — lisez-le avant d'écrire, car il code le style maison (lignes de badges centrées, boutons-badges de démo, tableaux, étapes ancrées, arbre du projet, bloc explicite « Judging Highlights »). references/badges.md contient des extraits shields.io prêts à copier-coller.

Suivez les étapes ci-dessous dans l'ordre, mais restez naturel — vous aidez un bâtisseur fatigué à franchir la ligne d'arrivée, pas à remplir un formulaire.

Étape 1 — Ancrer sur les critères d'évaluation (faites-le d'abord)

C'est la chose la plus importante que vous puissiez faire, et c'est pourquoi cette compétence existe. La plupart des READMEs sont écrits sur un modèle générique ; un README gagnant est écrit sur la grille d'évaluation. Avant tout, demandez :

« Avez-vous les critères d'évaluation ou la grille de notation de l'événement ? (par ex. 'innovation, difficulté technique, impact, qualité', ou une feuille de notation / message de page de soumission.) Si oui, collez-les — je m'assurerai que chacun soit visiblement traité. Sinon, j'utiliserai une grille par défaut solide. »

Pourquoi demander en premier : si la grille pondère « l'impact réel », commencez par un problème vivant et à qui il profite ; si elle pondère « la difficulté technique », mettez l'architecture et les parties difficiles en avant. Vous ajouterez plus tard une section Judging Highlights près de la fin qui nomme chaque critère et indique comment le projet y répond — c'est l'ancrage de la grille rendu visible, et les jurés adorent parce que ça fait leur travail à leur place. Tenez une liste de contrôle : chaque critère doit avoir une place dans le README.

S'ils n'ont pas de grille, utilisez par défaut les quatre critères que presque tous les événements utilisent dans une certaine version : innovation/originalité, exécution technique, impact/utilité, et qualité/achèvement.

Évaluez aussi la saveur de l'événement, car elle change les sections optionnelles qui conviennent (voir Étape 4) :

• Académique / recherche / techsprint (par ex. événements ACM) : récompense souvent une déclaration d'utilisation de l'IA, une note sur l'éthique/protection des données, des références/citations, et parfois un alignement avec les ODD de l'ONU. Incluez-les.
• Produit / startup / hackathon général de week-end : restez léger — ignorez les ODD, l'éthique et les citations sauf si le projet implique vraiment la collecte de données ou des affirmations nécessitant des sources.

En cas de doute, demandez, ou incluez l'ensemble plus léger et mentionnez que les autres sont disponibles.

Étape 2 — Parcourir le dépôt pour s'ancrer dans les faits

Les jurés perdent instantanément confiance quand un README décrit un projet qui ne correspond pas au code, ou quand les étapes de configuration ne fonctionnent pas. Avant d'écrire, regardez ce qui existe réellement. Le style maison fait référence à des chemins de fichiers réels et montre des commandes réelles avec les sorties attendues — vous ne pouvez le faire qu'en lisant le dépôt.

• Stack & langage: déduisez des manifests — package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile. Notez les frameworks (React, Next, Vite, FastAPI, Flask, Three.js…). Ceux-ci correspondent directement à la ligne de badges et au tableau de la stack technique.
• Comment l'exécuter : lisez scripts dans package.json, un Makefile, docker-compose.yml, Procfile, .env.example. La section d'exécution doit correspondre à la façon dont le projet démarre réellement, y compris les variables d'environnement et le port de développement réel. Là où vous pouvez déduire la sortie attendue, affichez-la — cela signale que le projet fonctionne.
• Structure & points d'entrée : parcourez les répertoires de premier niveau et le fichier d'entrée principal, de sorte que l'arbre du projet et les étapes « Comment ça marche » citent des fichiers réels (src/lib/check.js, app/main.py), comme dans les exemples.
• Ce qui existe déjà : un README partiel, LICENSE, captures d'écran dans assets//docs//public/, une URL déployée dans la configuration, des workflows CI. Réutilisez-le.

Si vous n'avez pas accès au dépôt (l'utilisateur décrit seulement le projet), ignorez le scan, appuyez-vous sur l'entretien, et dites-le — signalez que les commandes de configuration et les chemins de fichiers sont des espaces réservés à vérifier, plutôt que d'en inventer de précis.

Étape 3 — Interviewer pour ce que le code ne peut pas dire

Le dépôt donne les faits ; le bâtisseur donne l'histoire et la preuve. Demandez ceci en un seul lot convivial, et précisez qu'ils peuvent sauter tout élément :

• Argumentaire en une ligne → devient la citation d'accroche.
• Problème / inspiration → concret, humain, idéalement un moment spécifique.
• Démo en direct + vidéo → l'élément le plus cliqué. Mettez-les en évidence près du haut sous forme de boutons-badges. S'il n'y a pas de vidéo, notez gentiment qu'une vidéo de 2 minutes aide beaucoup.
• Captures d'écran / GIF / mascotte ou logo → même une seule image augmente la qualité perçue ; les exemples centrent une image mascotte/aperçu en haut.
• La partie difficile → ce qui était techniquement délicat ou ce dont ils sont fiers ; en or pour le score d'exécution technique et pour « Comment ça marche ».
• Résultats / métriques clés → si le projet a mesuré quelque chose, un petit tableau de résultats est très convaincant.
• Équipe → noms + rôles (et liens) pour le tableau de l'équipe.
• Prochaines étapes → feuille de route / mise à l'échelle montre la vision.
• Suppléments d'événement (uniquement si pertinent selon l'Étape 1) → outils IA utilisés, détails sur les données/consentement, citations.

Ne bloquez pas sur les réponses. S'ils manquent de temps, rédigez avec des espaces réservés clairement marqués comme <!-- TODO: lien vers la démo --> pour que rien d'important ne soit abandonné silencieusement — ne fabriquez jamais une URL de démo, une métrique ou un coéquipier.

Étape 4 — Rédiger le README

Produisez un seul fichier README.md à la racine du projet (ou là où l'utilisateur le souhaite), en suivant references/readme-template.md. Le squelette complet ordonné se trouve dans ce fichier ; voici la forme et les parties qui sont essentielles vs. optionnelles.

Essentiel (presque toujours inclus) :

1. Titre + optionnel logo/image mascotte centré(e)
2. Ligne de badges techniques centrée (depuis references/badges.md)
3. Ligne d'événement/soumission + citation d'accroche
4. Démo + vidéo sous forme de boutons-badges (et liens vers le jeu de données/Colab s'ils existent)
5. Tableau de l'équipe
6. Problème (ou « Pourquoi c'est important »)
7. Solution / Ce qu'il fait
8. Comment ça marche — étapes numérotées citant des fichiers réels
9. Tableau de la stack technique
10. Exécution locale — commandes vérifiées, avec sortie attendue si possible
11. Arbre de la structure du projet
12. Feuille de route / Prochaines étapes
13. Judging Highlights — une puce par critère, reliant le projet à celui-ci
14. Licence

Optionnel (inclure selon la saveur de l'événement et ce qui est réel) :

• Une barre de navigation de liens d'ancrage sous le hero (3 à 6 sections clés) — transforme un long défilement en un seul tap pour un juré qui parcourt sur un téléphone.
• Tableau des résultats / métriques clés + tableaux d'erreurs/analyses (projets de données) ; liez les données brutes ou une commande de reproduction pour que les chiffres soient reproductibles.
• Un tableau avant/après 50/50 quand le projet améliore un état de l'art (plus rapide, moins cher, moins d'étapes) — rend la victoire visuelle au lieu de simplement affirmée.
• Une boîte de statistiques ASCII sous le hero pour un projet avec un chiffre clé tueur.
• Des encadrés d'alerte GitHub > [!IMPORTANT] / > [!NOTE] pour attirer l'attention sur l'unique mise en garde ou fait clé qu'un juré parcourant ne doit pas manquer (à utiliser avec parcimonie).
• Diagramme de pipeline Mermaid (systèmes multi-étapes)
• Parcours de démo / type de visite « ce qui fonctionne hors ligne »
• Déclaration d'utilisation de l'IA (événements académiques)
• Protection des données / vie privée / éthique (projets impliquant des personnes ou des données)
• Alignement avec les ODD de l'ONU (événements académiques axés sur l'impact)
• Références et citations, remerciements
• Liste de contrôle de statut actuel + tâches de polissage avant jugement

Adaptez l'emphase et l'ordre à la grille de l'Étape 1 : les critères les plus importants doivent apparaître en premier. Ne garnissez pas inutilement — chaque section doit mériter sa place. Un hackathon produit peut utiliser uniquement l'ensemble essentiel ; un techsprint de recherche peut utiliser la plupart de l'ensemble optionnel. Adaptez au projet, pas à une liste de contrôle.

Notes de style importantes pour le jugement :

• Commencez par la chose la plus forte — innovation, ingénierie ou impact, selon l'accroche.
• Montrez, ne dites pas — un bouton-badge de démo, un GIF, une configuration en une commande, et un bloc de sortie attendue battent les adjectifs. Chaque affirmation impressionnante doit être vérifiable. Un tableau avant/après, une boîte de statistiques, ou un benchmark reproductible transforme une affirmation en preuve que le juré peut voir ou réexécuter.
• Faites travailler le hero — titre centré, logo/mascotte optionnel, ligne de badges, et une citation percutante doivent permettre à un juré de comprendre ce qu'est ce projet et pourquoi il est bon avant de défiler. Mettez les boutons de démo/vidéo ici, là où le premier clic atterrit.
• Ancrez tout dans le dépôt — chemins de fichiers réels, commandes réelles, le vrai port de développement. C'est ce qui rend le README digne de confiance et constitue le fil conducteur du style des exemples.
• Soyez honnête — ne prétendez pas avoir des fonctionnalités qui n'existent pas ; les jurés testent les choses, et une affirmation erronée coûte plus qu'une fonctionnalité manquante. Marquez le travail non terminé dans « prochaines étapes » ou une liste de contrôle de statut, pas comme terminé.
• Gardez-le parcourable — paragraphes courts, en-têtes significatifs, tableaux plutôt que murs de prose, lisible de haut en bas sur un téléphone en deux minutes.

Étape 5 — Boucler la boucle avec la grille

Avant de remettre le résultat, reprenez chaque critère de l'Étape 1 et confirmez que la section Judging Highlights (et le corps) y répond ; si un critère n'a pas de place, ajoutez-la. Ensuite, dites à l'utilisateur ce que vous avez fait — par exemple « Votre grille pondérait l'impact et la difficulté technique ; j'ai commencé par le problème pour l'impact, ajouté une note 'pourquoi c'était difficile' sous Comment ça marche, et le bloc Judging Highlights nomme les quatre. » Enfin, listez les espaces réservés restants (lien de démo, captures d'écran, métriques) pour qu'ils sachent exactement quoi remplir avant de soumettre.