Jazztinn/dontreadme

Hackathon README Builder

Ein Hackathon-README hat eine Aufgabe, die ein normes Projekt-README nicht hat: Es muss gewinnen. Juroren überfliegen Dutzende Repos in Minuten, oft auf dem Handy, und entscheiden, was überhaupt geöffnet wird. Das README ist der erste Eindruck des Projekts und oft das einzige Artefakt, das ein Juror vor der Bewertung liest. Das Ziel ist also nicht „den Code zu dokumentieren“ – sondern einen vielbeschäftigten, skeptischen Juror schnell davon zu überzeugen, das Projekt zu verstehen und zu glauben, und jede Behauptung mühelos überprüfbar zu machen.

Dieses Skill produziert ein reichhaltiges, einreichungsorientiertes README, kein spärliches. Das Referenz-Erscheinungsbild lebt in references/readme-template.md – lies es vor dem Schreiben, denn es kodiert den Hausstil (zentrierte Badge-Zeilen, Demo-Badge-Buttons, Tabellen, nachvollziehbare Schritte, einen Projektbaum, einen expliziten Judging-Highlights-Block). references/badges.md enthält kopierbare shields.io-Snippets.

Arbeite die folgenden Schritte in der angegebenen Reihenfolge ab, bleibe aber gesprächig – du hilfst einem müden Builder über die Ziellinie, nicht beim Ausfüllen eines Formulars.

Schritt 1 – An den Bewertungskriterien verankern (dies zuerst tun)

Dies ist das wirksamste, was du tun kannst, und der Grund, warum dieses Skill existiert. Die meisten READMEs werden nach einer generischen Vorlage geschrieben; ein gewinnendes wird nach der Bewertungsrubrik geschrieben. Frage als Erstes:

„Hast du die Bewertungskriterien oder die Rubrik des Events zur Hand? (z.B. 'Innovation, technische Schwierigkeit, Einfluss, Poliertheit' oder ein Bewertungsbogen / Einreichungsseite.) Füge sie ein, wenn ja – ich stelle sicher, dass jedes sichtbar adressiert wird. Wenn nicht, verwende ich eine starke Standardeinstellung.“

Warum zuerst fragen: Wenn die Rubrik „realer Einfluss“ gewichtet, führe mit einem lebendigen Problem und wem es hilft; wenn sie „technische Schwierigkeit“ gewichtet, stelle die Architektur und die schwierigen Teile voran. Du wirst später einen Judging-Highlights-Abschnitt in der Nähe des Endes hinzufügen, der jedes Kriterium benennt und darauf verweist, wie das Projekt es erfüllt – dies ist die sichtbare Verankerung an der Rubrik, und Juroren lieben es, weil es deren Arbeit erledigt. Führe eine Checkliste: Jedes Kriterium braucht einen Platz im README.

Wenn sie keine Rubrik haben, weiche auf die vier Kriterien aus, die fast jedes Event in irgendeiner Version verwendet: Innovation/Originalität, technische Ausführung, Einfluss/Nützlichkeit und Poliertheit/Vollständigkeit.

Prüfe auch den Charakter des Events, denn er beeinflusst, welche optionalen Abschnitte dazugehören (siehe Schritt 4):

• Akademisch / Forschung / Techsprint (z.B. ACM-Events): belohnt oft eine Offenlegung der KI-Nutzung, eine Ethik-/Datenschutznotiz, Referenzen/Zitate und manchmal eine Ausrichtung an den UN-Nachhaltigkeitszielen (SDGs). Füge diese ein.
• Produkt / Startup / allgemeines Wochenend-Hackathon: halte es schlank – lasse SDGs, Ethik und Zitate weg, es sei denn, das Projekt beinhaltet die Erhebung von Daten oder Behauptungen, die belegt werden müssen.

Wenn du unsicher bist, frage oder füge die leichtere Menge hinzu und erwähne, dass die anderen verfügbar sind.

Schritt 2 – Das Repository scannen, um dich auf Fakten zu stützen

Juroren verlieren sofort das Vertrauen, wenn ein README ein Projekt beschreibt, das nicht zum Code passt, oder wenn die Einrichtungsschritte nicht funktionieren. Also schau vor dem Schreiben, was wirklich da ist. Der Hausstil verweist auf echte Dateipfade und zeigt echte Befehle mit erwarteter Ausgabe – du kannst das nur tun, indem du das Repository liest.

• Stack & Sprache: Erschließe aus Manifesten – package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile. Notiere Frameworks (React, Next, Vite, FastAPI, Flask, Three.js…). Diese fließen direkt in die Badge-Zeile und die Tech-Stack-Tabelle ein.
• Wie man es ausführt: Lies scripts in package.json, eine Makefile, docker-compose.yml, Procfile, .env.example. Der Ausführungsabschnitt muss mit der tatsächlichen Startweise des Projekts übereinstimmen, einschließlich Umgebungsvariablen und dem echten Entwicklungsport. Wo du die erwartete Ausgabe ableiten kannst, zeige sie – sie signalisiert, dass das Ding funktioniert.
• Struktur & Einstiegspunkte: Überfliege die Verzeichnisse der obersten Ebene und die Haupt-Einstiegsdatei, damit der Projektbaum und die Schritte zur Funktionsweise echte Dateien zitieren (src/lib/check.js, app/main.py), so wie die Beispiele es tun.
• Was bereits existiert: ein teilweises README, LICENSE, Screenshots in assets//docs//public/, eine bereitgestellte URL in der Konfiguration, CI-Workflows. Nutze es wieder.

Wenn du keinen Repository-Zugriff hast (der Benutzer beschreibt das Projekt nur), überspringe den Scan, verlasse dich auf das Interview und sag es – markiere, dass die Setup-Befehle und Dateipfade Platzhalter sind, die zu überprüfen sind, anstatt genaue zu erfinden.

Schritt 3 – Interview für das, was dir der Code nicht sagen kann

Das Repository liefert Fakten; der Builder liefert die Geschichte und den Beweis. Frage nach diesen in einer freundlichen Charge und mache klar, dass sie alles überspringen können:

• Einzeiler-Pitch → wird der Tagline-Blockquote.
• Problem / Inspiration → konkret, menschlich, idealerweise ein bestimmter Moment.
• Live-Demo + Video → das am häufigsten angeklickte Asset. Platziere beide als Badge-Buttons in der Nähe des Anfangs. Wenn es kein Video gibt, merke sanft an, dass eines von 2 Minuten sehr hilft.
• Screenshots / GIF / Maskottchen oder Logo → schon ein einziges Bild steigert die wahrgenommene Poliertheit; die Beispiele zentrieren oben ein Maskottchen/Vorschaubild.
• Der schwierige Teil → was technisch knifflig war oder worauf sie stolz sind; Gold für die Bewertung der technischen Ausführung und für „Wie es funktioniert“.
• Schlagzeilenergebnisse / Metriken → wenn das Projekt etwas gemessen hat, ist eine kleine Ergebnistabelle sehr überzeugend.
• Team → Namen + Rollen (und Links) für die Teamtabelle.
• Was als Nächstes kommt → Roadmap/Skalierung zeigt Vision.
• Event-Extras (nur relevant gemäß Schritt 1) → verwendete KI-Tools, Daten-/Einwilligungsdetails, Zitate.

Hänge dich nicht an Antworten auf. Wenn ihnen die Zeit ausgeht, schreibe einen Entwurf mit klar markierten Platzhaltern wie <!-- TODO: Demo-Link hinzufügen -->, damit nichts Wichtiges stillschweigend weggelassen wird – erfinde niemals eine Demo-URL, eine Metrik oder einen Teammitglied.

Schritt 4 – Das README schreiben

Erstelle eine einzelne README.md im Projektstammverzeichnis (oder wo der Benutzer es möchte), die references/readme-template.md folgt. Das vollständige geordnete Skelett ist in dieser Datei; hier ist die Struktur und welche Teile Kern vs. optional sind.

Kern (fast immer enthalten):

1. Titel + optional zentriertes Logo/Maskottchen-Bild
2. Zentrierte Tech-Badge-Zeile (aus references/badges.md)
3. Event-/Einreichungszeile + Tagline-Blockquote
4. Demo + Video als Badge-Buttons (und Dataset/Colab-Links, falls vorhanden)
5. Teamtabelle
6. Problem (oder „Warum das wichtig ist“)
7. Lösung / Was es tut
8. Wie es funktioniert – nummerierte Schritte unter Verweis auf echte Dateien
9. Tech-Stack-Tabelle
10. Lokal ausführen – verifizierte Befehle, mit erwarteter Ausgabe, wo möglich
11. Projektstrukturbaum
12. Roadmap / Was als Nächstes kommt
13. Judging Highlights – ein Aufzählungspunkt pro Kriterium, das auf das Projekt abbildet
14. Lizenz

Optional (je nach Event-Art und was real ist):

• Ein Navigationsbalken mit Ankerlinks unter dem Helden (3–6 Hauptabschnitte) – verwandelt einen langen Bildlauf in einen Tipp für einen Richter, der auf dem Handy überfliegt.
• Schlagzeilenergebnisse / Metriktabelle + Fehler-/Analysetabellen (Datenprojekte); verlinke die Rohdaten oder einen Reproduktionsbefehl, damit die Zahlen nachvollziehbar sind.
• Eine Vorher/Nachher 50/50-Tabelle, wenn das Projekt einen Status quo verbessert (schneller, billiger, weniger Schritte) – sie macht den Gewinn sichtbar statt behauptet.
• Eine ASCII-Statistikkiste unter dem Helden für ein Projekt mit einer Killerzahl.
• > [!IMPORTANT] / > [!NOTE] GitHub-Alarm-Kästen, um den einen Vorbehalt oder die entscheidende Tatsache hervorzuheben, die ein überfliegender Juror nicht verpassen darf (sparsam verwenden).
• Mermaid-Pipeline-Diagramm (mehrstufige Systeme)
• Demo-Flow / „Was offline funktioniert“-Stil-Durchgang
• Offenlegung der KI-Nutzung (akademische Events)
• Datenschutz / Privatsphäre / Ethik (Projekte mit Menschen oder Daten)
• Ausrichtung an UN-Nachhaltigkeitszielen (wirkungsorientierte akademische Events)
• Referenzen & Zitate, Danksagungen
• Checkliste zum aktuellen Status + To-dos für die Poliertheit vor der Bewertung

Passe Betonung und Reihenfolge an die Rubrik aus Schritt 1 an: Die Kriterien, die am wichtigsten sind, sollten am höchsten erscheinen. Füge nichts auf – jeder Abschnitt sollte seinen Platz verdienen. Ein schlankes Produkt-Hackathon verwendet vielleicht nur den Kern; ein Forschungstechsprint verwendet vielleicht die meiste optionale Menge. Passe an das Projekt an, nicht an eine Checkliste.

Stilnotizen, die für die Bewertung wichtig sind:

• Führe mit dem Stärksten an – Innovation, Technik oder Wirkung, je nachdem, was der Aufhänger ist.
• Zeige, erzähle nicht – ein Demo-Badge-Button, ein GIF, eine Ein-Befehl-Einrichtung und ein Block mit erwarteter Ausgabe schlagen Adjektive. Jede beeindruckende Behauptung sollte überprüfbar sein. Eine Vorher/Nachher-Tabelle, eine Statistikbox oder ein reproduzierbarer Benchmark verwandelt eine Behauptung in einen Beweis, den der Richter sehen oder neu ausführen kann.
• Lasse den Helden arbeiten – zentrierter Titel, optionales Logo/Maskottchen, Badge-Zeile und ein prägnanter Tagline sollten es einem Richter ermöglichen, zu erfassen, was das ist und warum es gut ist, bevor er scrollt. Platziere die Demo/Video-Buttons hier, wo der erste Klick landet.
• Verankere alles im Repository – echte Dateipfade, echte Befehle, der echte Entwicklungsport. Dies macht das README vertrauenswürdig und ist der rote Faden des Beispielstils.
• Sei ehrlich – behaupte keine Funktionen, die es nicht gibt; Richter testen Dinge, und eine gebrochene Behauptung kostet mehr als eine fehlende Funktion. Markiere unvollständige Arbeit unter „Was als Nächstes kommt“ oder einer Status-Checkliste, nicht als erledigt.
• Halte es überfliegbar – kurze Absätze, aussagekräftige Überschriften, Tabellen statt Textwänden, von oben nach unten auf dem Handy in zwei Minuten lesbar.

Schritt 5 – Die Schleife zur Rubrik schließen

Bevor du es übergibst, nimm jedes Kriterium aus Schritt 1 und bestätige, dass der Abschnitt Judging Highlights (und der Haupttext) es adressiert; wenn einem Kriterium ein Platz fehlt, füge ihn hinzu. Sage dem Benutzer dann, was du getan hast – z.B. „Deine Rubrik gewichtete Impact und technische Schwierigkeit; ich habe mit dem Problem für Impact begonnen und eine Notiz 'warum das schwer war' unter Wie es funktioniert hinzugefügt, und der Judging-Highlights-Block benennt alle vier.“ Liste schließlich alle verbleibenden Platzhalter auf (Demolink, Screenshots, Metriken), damit sie genau wissen, was sie vor der Einreichung ausfüllen müssen.