Respuesta rápida: ¿qué hace bueno a un README de proyecto?
Un buen README de un proyecto de GitHub permite entender el resultado, ejecutar el proyecto y decidir qué hacer después. Empieza con un resumen sencillo y ofrece el camino más corto hacia una ejecución correcta: requisitos, instalación, ejemplo mínimo y resultado esperado. Después añade configuración, estructura, contribución, licencia y limitaciones.
La intención de cómo escribir un buen README para tu proyecto de GitHub no es la misma que la de un Profile README personal. Un README de repositorio documenta software, datos, una web, un paquete o un experimento; un Profile README presenta a una persona. Para este último caso consulta la guía de plantillas de Profile README. Esta página se concentra en onboarding y mantenimiento del proyecto.
El README debe reducir las preguntas que tiene que hacer una persona nueva. No obligues al lector a adivinar el runtime, copiar comandos de una issue antigua o buscar dónde empieza la demo. Un README.md breve con comandos correctos es mejor que una página vistosa que no permite pasar del clon al primer resultado.
Las imágenes y los widgets son pruebas de apoyo. Una captura, un diagrama, un GIF breve o un badge de tests pueden ayudar, pero siempre deben acompañar una explicación. Para la sintaxis y el mantenimiento de badges, consulta la guía de badges para README.
Secciones del README que merecen espacio
Usa esta tabla como una plantilla README para un proyecto de GitHub. No todos los repositorios necesitan todas las secciones, pero la primera persona debe encontrar el propósito, la primera ejecución y el siguiente enlace útil sin buscar entre párrafos.
Ordena las secciones según el trabajo del lector. Una demo pública puede ir arriba; una librería necesita instalación y ejemplos de API; una herramienta interna necesita variables de entorno y límites de acceso. Mantén títulos literales para que el esquema de GitHub sea fácil de escanear.
| Sección | Objetivo | Conservar | Evitar |
|---|---|---|---|
| Resumen del proyecto | Explicar qué hace y para quién es. | Resultado concreto, alcance y estado. | Un eslogan que no nombra el caso de uso. |
| Funciones y demo | Mostrar lo que el visitante puede ver o usar. | Lista breve, demo, salida o captura. | Prometer funciones que la rama actual no tiene. |
| Requisitos | Evitar sorpresas durante la instalación. | Runtime, sistema, dependencias y versiones compatibles. | Suponer que todos conocen tu entorno. |
| Instalación | Pasar del clon a un entorno funcional. | Comandos en el orden correcto y directorio de trabajo. | Comandos antiguos de una issue o sin contexto. |
| Uso y configuración | Explicar el camino principal y sus opciones. | Ejemplo mínimo, entradas, salidas y variables de entorno. | Una referencia completa antes del primer resultado. |
| Estructura | Ayudar a navegar el repositorio. | Carpetas y archivos que necesita un usuario o colaborador. | Listar cada archivo generado. |
| Contribución | Fijar expectativas para issues y pull requests. | Tests, estilo, ramas y comprobaciones locales. | Invitar a contribuir sin explicar cómo verificar cambios. |
| Licencia y límites | Aclarar reutilización y fronteras. | Licencia, limitaciones, datos y notas de seguridad. | Sugerir garantías que el proyecto no ofrece. |
Flujo de trabajo en cinco pasos
Escribe el README desde la primera tarea del lector, no desde el orden en que construiste el código. Este flujo sirve para un repositorio nuevo y para actualizar uno después de una versión. Redacta primero; añade capturas y badges cuando el camino principal sea exacto.
Un README también es una superficie de mantenimiento. Cuando cambia un comando, una rama, una variable, una captura o la URL de la demo, revisa el README dentro del mismo cambio.
Define lector y resultado
Decide si la primera persona es usuaria, colaboradora, revisora, estudiante o evaluadora. Especifica qué debe conseguir en cinco minutos.
Dibuja el camino más corto
Escribe resumen, requisitos, instalación, ejemplo mínimo y salida esperada. Si no es claro, todavía no añadas decoración.
Añade pruebas y contexto
Incluye funciones, demo, captura, salida, arquitectura o señal de tests para evaluar el repositorio sin leer todos los archivos.
Documenta configuración y contribución
Explica variables, ajustes opcionales, estructura, comprobaciones locales, issues, licencia y limitaciones conocidas.
Ejecuta el README como una prueba
Clona el repositorio en limpio, sigue los comandos, abre enlaces e imágenes y revisa la página en móvil antes de fusionar.
Ejemplos por tipo de proyecto
El mejor README para mostrar un proyecto no siempre es el más largo. Ajusta las pruebas y los pasos de instalación a lo que realmente entrega el repositorio. Una CLI debe sentirse rápida; una aplicación web necesita demo y variables; una librería necesita un ejemplo de API copiable.
Los ejemplos sirven para distinguir una sección útil de una plantilla genérica. Puedes reutilizar los títulos, pero las pruebas, comandos y límites deben salir del repositorio real.
CLI o automatización
Muestra el problema, comando de instalación, entrada y salida, opciones, códigos de salida y una forma segura de probarla.
Aplicación web
Empieza con demo o captura, enumera runtime y variables, explica el arranque local y aclara si incluye datos de ejemplo.
Librería o paquete
Pon arriba el comando de instalación y el import mínimo. Añade runtimes, API, política de versiones y cambios incompatibles.
Datos o investigación
Documenta fuente, preparación, salida esperada, límites de reproducibilidad, licencia y cómo inspeccionar o citar el resultado.
Proyecto comunitario
Haz visible la contribución: entorno local, tests, formato, etiquetas de issues, código de conducta y decisiones de diseño.
Cómo usar imágenes, badges y demos
Una imagen debe responder una pregunta que el texto respondería lentamente. Usa una captura para enseñar la interfaz, un diagrama para explicar arquitectura, una salida para mostrar un archivo generado o una animación breve si importa la interacción. Añade texto alternativo y coloca el recurso junto a la sección que explica.
Los badges son metadatos opcionales, no documentación. Una fila pequeña puede mostrar build, versión, licencia o cobertura si la fuente es verificable. La guía de badges para README explica patrones Markdown estables. Quita badges obsoletos en vez de dejar una imagen rota como primera impresión.
Las visualizaciones de actividad pueden aportar contexto al perfil de una persona mantenedora, pero no demuestran que un repositorio sea útil. Si enlazas un gráfico, una tarjeta de estadísticas o una vista 3D, explica qué mide y deja que el comportamiento, los tests y los ejemplos sean la prueba principal.
Regla sencilla
Si un recurso visual no ayuda a entender, ejecutar, evaluar o confiar en el proyecto, muévelo hacia abajo o elimínalo. La conclusión debe estar en HTML, no dentro de una imagen.
Comprobaciones antes de publicar
Trata el README como un artefacto de release. Una prueba limpia en terminal o navegador detecta más problemas que una revisión final de ortografía.
| Problema | Causa probable | Solución |
|---|---|---|
| Falla el primer comando | Falta runtime, directorio incorrecto, rama antigua o variable no documentada. | Prueba la guía desde un clon limpio y actualiza requisitos y orden de comandos. |
| No se entiende el resultado | Hay comandos pero no una salida o señal de éxito. | Incluye una salida, captura, URL, test o ruta de archivo pequeña. |
| Demo o imagen rota | Rama renombrada, asset privado, ruta relativa incorrecta o despliegue eliminado. | Abre cada enlace e imagen desde la página renderizada y usa rutas estables. |
| La configuración es un misterio | Las variables solo aparecen en el código. | Lista valores necesarios, ejemplos seguros, defaults y gestión de secretos. |
| No se pueden verificar cambios | No hay comando documentado de tests, lint o formato. | Añade las comprobaciones locales esperadas antes de un pull request. |
| Difícil de leer en móvil | Imágenes enormes, tablas anchas o filas largas de badges. | Comprime recursos, limita tablas, usa títulos claros y revisa un viewport pequeño. |
| Las promesas superan al proyecto | Texto de marketing copiado de una hoja de ruta antigua. | Relaciona cada función con una demo, comando, test o limitación vigente. |
Preguntas frecuentes sobre README de proyectos
¿Qué pongo al principio del README?
El nombre, el resultado en una frase, el estado actual y el enlace o comando más rápido para verlo funcionar. Deja el contexto largo después de la guía rápida.
¿Subir el proyecto a GitHub crea un README?
No. GitHub puede inicializar un repositorio con README al crearlo, pero subir un proyecto local no genera documentación. Añade y confirma README.md tú mismo.
¿Debo incluir toda la estructura de carpetas?
Solo muestra carpetas y archivos que ayuden a navegar. Un árbol corto y comentado es mejor que un listado generado que cambia en cada build.
¿Puedo usar un generador o prompt?
Sí, para crear un esquema, pero verifica comandos, rutas, dependencias, funciones, capturas y licencia frente al repositorio. El texto generado no es una prueba.
¿Dónde coloco los badges?
Una fila pequeña puede ir junto al título o el estado del proyecto si está actualizada. No dejes que empuje la instalación y el uso fuera de la zona visible.
¿Cómo evito que el README quede obsoleto?
Revísalo con cada release y pull request, prueba la guía periódicamente, elimina enlaces viejos y trata variables, versiones y demos como datos mantenidos.