Jazztinn/dontreadme

Constructor de README para Hackathons

Un README de hackathon tiene un trabajo que un README de proyecto normal no tiene: ganar. Los jueces hojean docenas de repositorios en minutos, a menudo en un teléfono, decidiendo qué vale la pena abrir. El README es la primera impresión del proyecto y, a menudo, el único artefacto que un juez lee antes de puntuar. Así que el objetivo no es "documentar el código" — es hacer que un juez ocupado y escéptico entienda y crea en el proyecto rápidamente, y que cada afirmación sea trivialmente verificable.

Esta habilidad produce un README rico, estilo presentación, no uno escueto. La referencia visual está en references/readme-template.md — léelo antes de escribir, porque codifica el estilo de la casa (filas de insignias centradas, botones de demostración tipo insignia, tablas, pasos fundamentados, un árbol del proyecto, un bloque explícito de "Highlights de Evaluación"). references/badges.md tiene fragmentos copiables de shields.io.

Sigue los pasos a continuación en orden, pero mantén un tono conversacional: estás ayudando a un desarrollador cansado a cruzar la línea de meta, no llenando un formulario.

Paso 1 — Ancla en los criterios de evaluación (haz esto primero)

Esto es lo de mayor apalancamiento que puedes hacer, y es por lo que existe esta habilidad. La mayoría de los README se escriben para una plantilla genérica; uno ganador se escribe para la rúbrica. Antes de cualquier otra cosa, pregunta:

"¿Tienes a mano los criterios de evaluación o la rúbrica del evento? (por ejemplo, 'innovación, dificultad técnica, impacto, pulido', o una hoja de puntuación / indicaciones de la página de presentación). Pégalo si tienes — me aseguraré de que cada uno se aborde visiblemente. Si no, usaré un conjunto predeterminado sólido."

Por qué preguntar primero: si la rúbrica pondera "impacto en el mundo real", comienza con un problema vívido y a quién ayuda; si pondera "dificultad técnica", pon la arquitectura y las partes difíciles al principio. Más adelante agregarás una sección de Aspectos Destacados para la Evaluación cerca del final que nombre cada criterio y señale cómo el proyecto lo cumple — esto es el anclaje de la rúbrica hecho visible, y a los jueces les encanta porque les hace el trabajo. Mantén una lista de verificación: cada criterio necesita un lugar en el README.

Si no tienen rúbrica, usa por defecto los cuatro criterios que casi todos los eventos utilizan en alguna versión: innovación/originalidad, ejecución técnica, impacto/utilidad, y pulido/integridad.

También evalúa el estilo del evento, porque cambia qué secciones opcionales corresponden (ver Paso 4):

• Académico / investigación / techsprint (por ejemplo, eventos ACM): a menudo recompensa una declaración de uso de IA, una nota de ética/protección de datos, referencias/citas y, a veces, alineación con los ODS de la ONU. Inclúyelos.
• Producto / startup / hackathon general de fin de semana: mantenlo ágil — omite ODS, ética y citas a menos que el proyecto realmente implique recolección de datos o afirmaciones que necesiten respaldo.

Cuando no estés seguro, pregunta, o incluye el conjunto más ligero y menciona que los otros están disponibles.

Paso 2 — Escanea el repositorio para fundamentarte en hechos

Los jueces pierden confianza instantáneamente cuando un README describe un proyecto que no coincide con el código, o cuando los pasos de configuración no funcionan. Así que antes de escribir, mira lo que realmente hay. El estilo de la casa referencia rutas de archivos reales y muestra comandos reales con salida esperada — solo puedes hacerlo leyendo el repositorio.

• Stack y lenguaje: infiérelo a partir de manifiestos — package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile. Anota frameworks (React, Next, Vite, FastAPI, Flask, Three.js…). Estos se asignan directamente a la fila de insignias y a la tabla de stack tecnológico.
• Cómo ejecutarlo: lee scripts en package.json, un Makefile, docker-compose.yml, Procfile, .env.example. La sección de ejecución debe coincidir con cómo realmente se inicia el proyecto, incluyendo variables de entorno y el puerto de desarrollo real. Donde puedas inferir la salida esperada, muéstrala — indica que la cosa funciona.
• Estructura y puntos de entrada: hojea los directorios de nivel superior y el archivo de entrada principal para que el árbol del proyecto y los pasos de "Cómo funciona" citen archivos reales (src/lib/check.js, app/main.py), como lo hacen los ejemplos.
• Lo que ya existe: un README parcial, LICENCIA, capturas de pantalla en assets//docs//public/, una URL desplegada en la configuración, flujos de CI. Reutilízalo.

Si no tienes acceso al repositorio (el usuario solo describe el proyecto), omite el escaneo, apóyate en la entrevista, y dilo — indica que los comandos de configuración y las rutas de archivos son marcadores de posición a verificar, en lugar de inventar los exactos.

Paso 3 — Entrevista para lo que el código no puede decirte

El repositorio da hechos; el constructor da la historia y la prueba. Pide estos en un lote amigable, y deja claro que pueden omitir cualquier cosa:

• Presentación de una línea → se convierte en la cita destacada.
• Problema / inspiración → concreto, humano, idealmente un momento específico.
• Demo en vivo + video → el activo más cliqueado. Pon ambos cerca de la parte superior como botones de insignia. Si no hay video, nota suavemente que uno de 2 minutos ayuda mucho.
• Capturas de pantalla / GIF / mascota o logo → incluso una imagen eleva el pulido percibido; los ejemplos centran una imagen de mascota/vista previa arriba.
• La parte difícil → lo que fue técnicamente complicado o de lo que están orgullosos; oro para la puntuación de ejecución técnica y para "Cómo funciona".
• Resultados / métricas principales → si el proyecto midió algo, una pequeña tabla de resultados es muy persuasiva.
• Equipo → nombres + roles (y enlaces) para la tabla de equipo.
• Qué sigue → hoja de ruta/escalabilidad muestra visión.
• Extras del evento (solo si es relevante según el Paso 1) → herramientas de IA utilizadas, detalles de datos/consentimiento, citas.

No te detengas por falta de respuestas. Si se les acabó el tiempo, redacta con marcadores de posición claramente marcados como <!-- TODO: agregar enlace de demo --> para que nada importante se omita silenciosamente — nunca fabriques una URL de demo, una métrica o un compañero de equipo.

Paso 4 — Escribe el README

Produce un único README.md en la raíz del proyecto (o donde el usuario quiera), siguiendo references/readme-template.md. El esqueleto completo ordenado está en ese archivo; aquí está la estructura y qué partes son esenciales vs. opcionales.

Esencial (casi siempre incluir):

1. Título + logo/mascota centrado opcional
2. Fila de insignias tecnológicas centrada (de references/badges.md)
3. Línea de evento/presentación + cita destacada
4. Demo + video como botones de insignia (y enlaces a dataset/Colab si existen)
5. Tabla de equipo
6. Problema (o "Por qué esto importa")
7. Solución / Qué hace
8. Cómo funciona — pasos numerados citando archivos reales
9. Tabla de stack tecnológico
10. Ejecución local — comandos verificados, con salida esperada cuando sea posible
11. Árbol de estructura del proyecto
12. Hoja de ruta / Qué sigue
13. Aspectos destacados para la evaluación — un punto por criterio, mapeando el proyecto a él
14. Licencia

Opcional (incluir según el estilo del evento y lo que sea real):

• Una barra de navegación con enlaces de anclaje debajo del héroe (3–6 secciones clave) — convierte un desplazamiento largo en un toque para un juez que hojea en un teléfono.
• Tabla de resultados / métricas principales + tablas de error/análisis (proyectos de datos); enlaza los datos sin procesar o un comando de reproducción para que los números sean re-ejecutables.
• Una tabla 50/50 de antes/después cuando el proyecto mejora el statu quo (más rápido, más barato, menos pasos) — hace que la victoria sea visual en lugar de afirmada.
• Un cuadro de estadísticas ASCII debajo del héroe para un proyecto con un número impactante.
• Llamadas de alerta de GitHub > [!IMPORTANT] / > [!NOTE] para resaltar la única advertencia o hecho clave que un juez que hojea no debe perderse (úsalas con moderación).
• Diagrama de tubería Mermaid (sistemas de múltiples etapas)
• Recorrido del flujo de demo / "qué funciona sin conexión"
• Declaración de uso de IA (eventos académicos)
• Protección de datos / privacidad / ética (proyectos que involucran personas o datos)
• Alineación con los ODS de la ONU (eventos académicos orientados al impacto)
• Referencias y citas, agradecimientos
• Lista de verificación de estado actual + tareas de pulido previas a la evaluación

Adapta el énfasis y el orden a la rúbrica del Paso 1: los criterios que más importan deben aparecer más arriba. No rellenes — cada sección debe ganarse su lugar. Un hackathon de producto ágil podría usar solo el conjunto esencial; un techsprint de investigación podría usar la mayoría del conjunto opcional. Adáptate al proyecto, no a una lista de verificación.

Notas de estilo que importan para la evaluación:

• Empieza con lo más fuerte — innovación, ingeniería o impacto, cual sea el gancho.
• Muestra, no digas — un botón de insignia de demo, un GIF, una configuración de un solo comando y un bloque de salida esperada vencen a los adjetivos. Cada afirmación impresionante debe ser verificable. Una tabla de antes/después, un cuadro de estadísticas o un benchmark reproducible convierte una afirmación en una prueba que el juez puede ver o re-ejecutar.
• Haz que el héroe trabaje — título centrado, logo/mascota opcional, fila de insignias y una cinta precisa deben permitir que un juez comprenda qué es esto y por qué es bueno antes de desplazarse. Pon los botones de demo/video aquí, donde aterriza el primer clic.
• Fundamenta todo en el repositorio — rutas de archivos reales, comandos reales, el puerto de desarrollo real. Esto es lo que hace que el README sea confiable y es el hilo conductor del estilo de ejemplo.
• Sé honesto — no afirmes funcionalidades que no existen; los jueces prueban cosas, y una afirmación rota cuesta más que una funcionalidad faltante. Marca el trabajo incompleto bajo "qué sigue" o una lista de verificación de estado, no como completado.
• Mantenlo escaneable — párrafos cortos, encabezados significativos, tablas en lugar de muros de prosa, legible de arriba a abajo en un teléfono en dos minutos.

Paso 5 — Cierra el ciclo contra la rúbrica

Antes de entregar, toma cada criterio del Paso 1 y confirma que la sección de Aspectos destacados para la evaluación (y el cuerpo) lo aborda; si algún criterio carece de un lugar, agrégalo. Luego dile al usuario lo que hiciste — p. ej., "Tu rúbrica ponderó impacto y dificultad técnica; comencé con el problema para el impacto y agregué una nota de 'por qué esto fue difícil' en Cómo funciona, y el bloque de Aspectos destacados para la evaluación nombra los cuatro." Finalmente, enumera los marcadores de posición restantes (enlace de demo, capturas de pantalla, métricas) para que sepan exactamente qué completar antes de enviar.