El README es lo primero que ve la gente cuando abre tu repositorio, la página de tu paquete o tu carpeta de documentación. En unos segundos debe responder tres preguntas: qué es esto, por qué me importa y cómo empiezo. Un README claro hace que tu proyecto se use, reciba estrellas y atraiga colaboradores. Uno confuso manda a los visitantes de vuelta a los resultados de búsqueda.
Markdown es el formato estándar de los README, así que escribir uno bueno es sobre todo cuestión de estructura y claridad.
Empieza con una descripción de una frase
Justo debajo del nombre del proyecto, escribe una frase sencilla sobre lo que hace y para quién es. "Una herramienta de línea de comandos que convierte archivos CSV a JSON" es mejor que "Una solución de datos potente, flexible y de nueva generación". Si un desconocido no puede repetir tu frase a un amigo, reescríbela.
Opcionalmente añade algunas insignias de estado de compilación, versión y licencia. Mantenlas en una sola línea para que no empujen hacia abajo el contenido importante.
Muestra, no solo cuentes
La gente decide rápido si un proyecto merece su tiempo. Una captura, un GIF o un pequeño ejemplo de código cerca del inicio demuestra que el proyecto funciona y cómo se ve en uso.
$ csv2json datos.csv > datos.json
Incluye el ejemplo más pequeño posible que produzca un resultado visible. El uso avanzado puede ir después.
Instalación
Da comandos para copiar y pegar para la configuración más común e indica los requisitos previos, como la versión mínima de Node.js o las librerías de sistema necesarias.
```bash
npm install mi-paquete
```
Prueba estos pasos de vez en cuando en un equipo limpio. Las instrucciones de instalación se estropean más rápido que cualquier otra parte de un README.
Uso
Recorre los casos de uso principales en orden de la frecuencia con que la gente los necesita. Cada uno debe tener una breve explicación y un ejemplo ejecutable. Enlaza a la documentación completa para lo demás en vez de duplicarla aquí.
Estructura del proyecto y configuración
Si la instalación requiere variables de entorno o un archivo de configuración, enumera cada opción en una tabla con su nombre, valor por defecto y significado. Las tablas son ideales para esto.
| Opción | Por defecto | Descripción |
| ------- | ----------- | ------------------------------ |
| `port` | `3000` | Puerto en el que escucha |
| `debug` | `false` | Muestra registros detallados |
Contribuciones y soporte
Explica cómo reportar un error, proponer un cambio y ejecutar las pruebas. Indica dónde deben ir las preguntas. Una sección breve de contribución reduce la barrera para quienes colaboran por primera vez.
Licencia
Indica la licencia con claridad al final y añade un archivo LICENSE. Sin una, la posición legal por defecto es que nadie puede reutilizar tu código.
Hábitos de formato que ayudan
- Usa un único título de nivel uno para el nombre del proyecto y títulos de nivel dos para las secciones.
- Mantén los párrafos cortos y prefiere listas para pasos y opciones.
- Especifica el lenguaje en cada bloque de código para obtener resaltado de sintaxis.
- Usa textos de enlace descriptivos en lugar de "haz clic aquí".
- Añade un índice solo cuando el README sea lo bastante largo como para necesitarlo.
Previsualiza antes de confirmar
Las diferencias de renderizado causan muchos errores pequeños: una lista que no se anidó, una tabla con una barra vertical faltante, un bloque de código que nunca se cerró y se tragó el resto de la página. Pega tu borrador en el previsualizador de Markdown y léelo como lo haría un visitante antes de subirlo.
Un README nunca está terminado, pero uno claro, honesto y bien estructurado es la mejor inversión en documentación que puede hacer un proyecto pequeño.