Alguien llega a tu repositorio. Antes de leer una sola línea de tu código, lee tu README. En esos primeros segundos decide si el proyecto vale su tiempo, si resuelve su problema y si confía en que lo mantendrás. Un README claro convierte a los visitantes curiosos en usuarios y colaboradores. Uno confuso los envía de vuelta a los resultados de búsqueda. La buena noticia es que un gran README sigue una forma predecible, y Markdown te da todas las herramientas que necesitas para construirlo sin una sola línea de HTML.
Por qué tu README es lo primero que la gente ve
El README es la puerta de entrada de un proyecto. GitHub, GitLab y Bitbucket renderizan automáticamente el archivo llamado README.md en la página principal del repositorio, y npm lo muestra en la página del paquete. Eso significa que es la pieza de documentación más visitada que jamás escribirás. Trabaja mientras duermes, respondiendo las mismas preguntas una y otra vez para que tú no tengas que hacerlo. Un buen README reduce tu carga de soporte, acelera la incorporación de nuevos compañeros y hace que tu proyecto parezca mantenido y confiable.
Un README débil hace lo contrario. Si un visitante no logra entender qué hace el proyecto, cómo instalarlo o cómo ejecutarlo en unos treinta segundos, la mayoría simplemente se irá. La documentación es una funcionalidad, no una ocurrencia tardía. El tiempo que inviertes en un README claro se recupera cada vez que una persona adopta tu herramienta en lugar de escribir la suya o de abrir un issue que la documentación podría haber respondido.
Las secciones esenciales de un buen README
No necesitas una plantilla fija para cada proyecto, pero casi todos los buenos README responden las mismas preguntas en aproximadamente el mismo orden. Piensa en estas secciones como una lista de verificación que puedes recortar o ampliar según el tamaño del proyecto:
- Título y lema: el nombre del proyecto y una línea que diga qué es.
- Insignias: señales visuales rápidas del estado de compilación, la versión y la licencia.
- Descripción: un párrafo corto sobre qué hace el proyecto, por qué y para quién.
- Instalación: los comandos exactos necesarios para ponerlo en marcha.
- Uso: un ejemplo mínimo que demuestre que el proyecto funciona.
- Configuración: las opciones, variables de entorno o parámetros que se pueden cambiar.
- Contribución: cómo pueden ayudar otros y cuáles son tus estándares.
- Licencia: los términos legales bajo los que se comparte el código.
Los scripts pequeños quizá solo necesiten un título, una descripción y un bloque de uso. Las bibliotecas grandes merecen cada sección más una tabla de contenidos. Ajusta la ceremonia al tamaño del proyecto y nunca rellenes un README con secciones que quedan vacías.
Título, lema e insignias
Abre el archivo con un único encabezado de nivel superior usando una almohadilla: # Nombre del Proyecto. Esto se convierte en el título grande en la parte superior de la página renderizada. Justo debajo, agrega un lema de una línea en texto plano que capture la promesa del proyecto. Resiste la tentación de escribir dos párrafos aquí; el lema debe leerse como un titular, no como un ensayo.
Las insignias son pequeñas imágenes de estado que se sitúan cerca de la parte superior. No son más que imágenes de Markdown que apuntan a un servicio como Shields.io, escritas como . Las insignias comunes muestran el estado de compilación, la última versión publicada, la cobertura de pruebas, la licencia y el número de descargas. Dos o tres insignias bien elegidas indican que el proyecto está activo y sano. Un muro de veinte insignias solo genera ruido, así que mantén el conjunto pequeño y significativo.
Escribe una descripción que capte la atención
La descripción responde tres preguntas: qué hace esto, por qué existe y para quién es. Comienza por el problema que resuelve en lugar de la tecnología que hay detrás. Un lector que escanea rápido quiere saber "me va a ayudar esto" antes de que le importe cómo está construido. Mantén el primer párrafo en tres o cuatro oraciones y deja que el resto del README aporte el detalle.
Usa lenguaje claro y sustantivos concretos. En lugar de "una solución potente y flexible para flujos de trabajo modernos", escribe lo que realmente es: una herramienta de línea de comandos que renombra archivos en lote, o una biblioteca que valida direcciones de correo. La especificidad genera confianza. Si tu proyecto tiene una frase memorable, este es el lugar para usarla, pero acompáñala de inmediato con una explicación clara y literal.
Instrucciones de instalación que la gente puede seguir
La instalación es donde los lectores impacientes tienen éxito o se rinden, así que hazla infalible. Enumera primero cualquier requisito previo, como una versión mínima del entorno, y luego da el comando exacto dentro de un bloque de código cercado. Envuelve los comandos en triple acento grave con una pista de lenguaje comobash para que el bloque se resalte y, en muchas plataformas, muestre un botón de copiar. El lector debería poder copiar un bloque y pegarlo en una terminal sin editar nada.
Muestra primero la ruta de instalación más común y luego cualquier alternativa, como un gestor de paquetes distinto o una compilación desde el código fuente. Si tu herramienta necesita configuración antes de ejecutarse, menciónalo aquí y enlaza a la sección de configuración en lugar de volcar todas las opciones en los pasos de instalación. Mantén el camino feliz corto y los casos límite fuera del medio.
Ejemplos de uso y capturas de pantalla
Un único ejemplo que funciona vale más que una página de prosa. Muestra el fragmento más pequeño que produzca un resultado real, de nuevo envuelto en un bloque de código cercado con un identificador de lenguaje comojs, ts o python para el resaltado de sintaxis. Los lectores copian los ejemplos de uso al pie de la letra, así que asegúrate de que el código se ejecute exactamente como está escrito. Si tu proyecto tiene varias tareas comunes, da un ejemplo corto para cada una en lugar de un único bloque enorme.
Para cualquier cosa visual, agrega una captura de pantalla o un GIF animado corto usando la sintaxis de imagen. Una imagen de una interfaz de línea de comandos o de un componente renderizado responde preguntas que las palabras no pueden. Incluye siempre un texto alternativo descriptivo dentro de los corchetes para que la imagen sea accesible a los lectores de pantalla y siga siendo informativa cuando no se cargue.
Configuración, contribución y licencia
Las opciones de configuración son el caso clásico para una tabla de Markdown. Una tabla con columnas para el nombre de la opción, el tipo, el valor por defecto y la descripción se lee mucho más claro que una lista con viñetas. Constrúyela con barras verticales y guiones: una fila de encabezado, una fila separadora de guiones y una fila por opción. Si tu proyecto lee variables de entorno o un archivo de configuración, documenta cada clave y su efecto para que nadie tenga que leer el código fuente para aprender a ajustarlo.
La sección de contribución le dice a la gente cómo ayudar sin pisarte: cómo reportar errores, cómo proponer cambios y cuáles son tus estándares de código o de commits. Para proyectos más grandes, mantén esto corto y enlaza a un archivo CONTRIBUTING.md dedicado. Por último, indica siempre la licencia. Una línea clara como "Publicado bajo la Licencia MIT" con un enlace al archivo LICENSE elimina cualquier duda sobre cómo se puede usar el código. La falta de información de licencia bloquea en silencio a las empresas que quisieran adoptar tu trabajo.
Una plantilla de README lista para copiar
Para un script pequeño o un primer borrador no necesitas todas las secciones. Esta plantilla cubre lo esencial y nada más. Cópiala, reemplaza los marcadores de posición y tendrás un README respetable en minutos:
# Nombre del Proyecto
Una oración que explique qué hace el proyecto y para quién es.
## Instalación
```bash
npm install nombre-proyecto
```
## Uso
```js
import { saludar } from "nombre-proyecto";
saludar("mundo");
```
## Licencia
Publicado bajo la Licencia MIT.Una plantilla más completa para proyectos grandes
Cuando un proyecto crece hasta convertirse en una biblioteca o producto real, los lectores esperan más estructura. Esta segunda plantilla agrega insignias, una tabla de contenidos, una lista de funcionalidades y una tabla de configuración. Fíjate en cómo los enlaces de ancla de la tabla de contenidos apuntan a los encabezados usando identificadores en minúsculas y con guiones:
# Nombre del Proyecto
Una descripción corta y contundente del proyecto en una o dos oraciones.
## Tabla de Contenidos
- [Funcionalidades](#funcionalidades)
- [Instalación](#instalación)
- [Uso](#uso)
- [Configuración](#configuración)
- [Contribución](#contribución)
- [Licencia](#licencia)
## Funcionalidades
- Núcleo rápido y sin dependencias
- Funciona en Node y en el navegador
- Totalmente tipado con TypeScript
## Instalación
```bash
npm install nombre-proyecto
```
## Uso
```js
import { ejecutar } from "nombre-proyecto";
const resultado = ejecutar({ verbose: true });
console.log(resultado);
```
## Configuración
| Opción | Tipo | Defecto | Descripción |
|---|---|---|---|
| verbose | boolean | false | Imprime registros detallados |
| retries | number | 3 | Cuántas veces reintentar |
## Contribución
Los pull requests son bienvenidos. Para cambios importantes, abre un
issue primero para discutir lo que te gustaría cambiar.
## Licencia
MITConsejos de Markdown para pulir tu README
Unos pocos hábitos de Markdown marcan la diferencia entre un README que simplemente existe y uno que es un placer leer. Si todavía te estás familiarizando con la sintaxis en sí, nuestra guía de Markdown para principiantes cubre encabezados, listas, enlaces y tablas desde cero. Con lo básico dominado, estos toques elevan la calidad de cualquier README:
- Agrega una tabla de contenidos para archivos largos. Enlaza cada entrada a un encabezado con un ancla como
[Uso](#uso), usando la versión en minúsculas y con guiones del texto del encabezado. - Colapsa las secciones largas con las etiquetas HTML
<details>y<summary>, que los renderizadores de Markdown dejan pasar. Esto mantiene el detalle opcional disponible sin saturar la página. - Usa admoniciones donde estén soportadas. En GitHub, una cita que empieza con
> [!NOTE]o> [!WARNING]se renderiza como un aviso de color que atrae la vista. - Prefiere enlaces relativos a otros archivos del repositorio, como
[Contribución](CONTRIBUTING.md), para que los enlaces sigan funcionando en forks y espejos. - Previsualiza antes de hacer commit. El Markdown renderizado puede diferir de lo que imaginabas, sobre todo con tablas y listas anidadas, así que revisa siempre el resultado primero.
La forma más rápida de detectar una tabla rota o una cerca de código mal cerrada es verla renderizada mientras escribes. Prueba nuestro Editor de Markdown gratuito para redactar tu README con una vista previa en vivo lado a lado, y luego pega el archivo terminado directamente en tu repositorio. Un poco de pulido aquí da frutos cada vez que alguien abre tu proyecto.