Cómo escribir un README perfecto en Markdown

Guía paso a paso para crear un archivo README.md profesional para tus proyectos en GitHub. Estructura, badges, ejemplos, herramientas y errores comunes.

El archivo README.md es la carta de presentación de cualquier proyecto en GitHub. Es lo primero que ven los visitantes y puede marcar la diferencia entre que alguien use tu proyecto o lo ignore. Un buen README convierte un repositorio anónimo en un proyecto que inspira confianza.

¿Qué es un README?

Un README es un archivo Markdown que se muestra automáticamente en la página principal de un repositorio en GitHub, GitLab o Bitbucket. Su objetivo es explicar qué hace el proyecto, cómo instalarlo y cómo usarlo. GitHub renderiza el Markdown con soporte completo de la sintaxis básica y extendida, incluyendo tablas, listas de tareas, bloques de código con resaltado de sintaxis, diagramas Mermaid y alertas.

Estructura de un buen README

1. Título y descripción

El título y la descripción son lo primero que lee cualquier visitante. En menos de dos segundos, la persona decide si el proyecto le interesa o no. Un buen título debe ser claro y memorable, y la descripción debe explicar el problema que resuelve tu proyecto en una o dos frases.

# Nombre del Proyecto

Una descripción breve y clara de qué hace el proyecto y por qué es útil.

Un error frecuente es poner un título genérico como "Mi Proyecto" sin explicar qué hace. Siempre incluye una línea que responda: qué hace, para quién y por qué debería importarme.

2. Badges (opcional)

Los badges son indicadores visuales que transmiten confianza al usuario de un vistazo. Muestran si el proyecto se mantiene activo, qué licencia tiene, cuántas descargas acumula o si los tests pasan correctamente. Puedes generarlos fácilmente con shields.io.

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/badge/version-1.0.0-orange)

Algunos badges útiles que puedes agregar: estado del CI/CD, cobertura de tests, versión de npm/PyPI, cantidad de descargas y estrellas del repositorio. No abuses de los badges: 3 o 4 son suficientes. Demasiados badges generan ruido visual y diluyen la información importante.

3. Tabla de contenidos

La tabla de contenidos es esencial cuando tu README supera las 100 líneas. Permite al lector saltar directamente a la sección que le interesa sin tener que desplazarse por todo el documento. GitHub genera automáticamente anclas para cada encabezado, así que los enlaces internos funcionan sin configuración adicional.

## Tabla de contenidos

- [Instalación](#instalación)
- [Uso](#uso)
- [Contribuir](#contribuir)
- [Licencia](#licencia)

Si tu proyecto es grande, considera usar herramientas como doctoc para generar la tabla de contenidos automáticamente cada vez que cambies los encabezados.

4. Instalación

La sección de instalación debe ser tan clara que alguien sin experiencia previa en tu proyecto pueda seguirla paso a paso. Incluye los requisitos previos (versiones de Node, Python, etc.) y cada comando necesario. Si hay configuraciones especiales (variables de entorno, bases de datos), menciónalas aquí.

## Instalación

### Requisitos previos

- Node.js 18 o superior
- npm 9 o superior

### Pasos

​```bash
git clone https://github.com/usuario/proyecto.git
cd proyecto
npm install
cp .env.example .env
​```

Un consejo importante: después de escribir los pasos de instalación, pruébalos en un entorno limpio. Muchas veces omitimos pasos que damos por sentados (como instalar una dependencia del sistema o configurar una variable de entorno) porque nuestro equipo ya los tiene configurados.

5. Uso

La sección de uso es donde el lector decide si tu proyecto realmente le sirve. No basta con poner un solo comando: muestra los casos de uso más comunes con ejemplos reales. Si tu proyecto tiene una API, incluye al menos una llamada de ejemplo con su respuesta esperada.

## Uso

​```bash
npm start
​```

### Ejemplo básico

​```javascript
const miLib = require('mi-libreria');
const resultado = miLib.procesar('datos');
console.log(resultado);
​```

Si tu proyecto acepta argumentos o tiene diferentes modos de ejecución, documenta cada uno con un ejemplo concreto. Los usuarios prefieren copiar y pegar un ejemplo que funcione antes que leer una explicación abstracta.

6. Capturas de pantalla

Si tu proyecto tiene una interfaz visual (web, CLI con colores, app de escritorio), incluye capturas de pantalla o GIFs animados. Una imagen transmite la experiencia de uso mucho más rápido que una descripción en texto. Para capturas de CLI, herramientas como asciinema o VHS generan GIFs animados de sesiones de terminal.

## Capturas de pantalla

![Interfaz principal](screenshots/main.png)
![Línea de comandos](screenshots/cli.gif)

Guarda las imágenes en una carpeta screenshots/ o docs/images/ dentro del repositorio. Evita enlazar a servicios externos que puedan caer o cambiar las URLs.

7. Contribuir

Esta sección establece las reglas del juego para colaboradores. Un proyecto sin guía de contribución ahuyenta a posibles contribuidores porque no saben por dónde empezar ni qué convenciones seguir. Explica el flujo de trabajo, las convenciones de commits y cómo ejecutar los tests antes de enviar un PR.

## Contribuir

1. Haz un fork del repositorio
2. Crea una rama (`git checkout -b feature/nueva-funcionalidad`)
3. Haz commit de tus cambios (`git commit -m 'Añadir nueva funcionalidad'`)
4. Haz push a la rama (`git push origin feature/nueva-funcionalidad`)
5. Abre un Pull Request

Para proyectos grandes, considera crear un archivo CONTRIBUTING.md separado con instrucciones más detalladas (configuración del entorno de desarrollo, estilo de código, proceso de revisión) y enlazarlo desde el README.

8. Licencia

La licencia define legalmente qué pueden y qué no pueden hacer otros con tu código. Sin licencia, nadie puede legalmente usar, copiar ni modificar tu proyecto, aunque sea público. Las licencias más comunes en código abierto son MIT (muy permisiva), Apache 2.0 (con protección de patentes) y GPL (obliga a mantener el código abierto).

## Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo [LICENSE](LICENSE) para más detalles.

Si no sabes qué licencia elegir, choosealicense.com te ayuda a decidir en función de lo que quieres permitir.

Ejemplo completo de README

A continuación, un README completo y real que puedes usar como referencia. También puedes copiar nuestra plantilla de README como punto de partida.

# TaskFlow CLI

Herramienta de línea de comandos para gestionar tareas y proyectos
directamente desde la terminal.

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/badge/version-2.1.0-orange)
![npm downloads](https://img.shields.io/npm/dm/taskflow-cli)

## Tabla de contenidos

- [Características](#características)
- [Instalación](#instalación)
- [Uso](#uso)
- [Configuración](#configuración)
- [Contribuir](#contribuir)
- [Licencia](#licencia)

## Características

- Crear, editar y eliminar tareas desde la terminal
- Organizar tareas por proyectos y etiquetas
- Exportar tareas a Markdown y JSON
- Sincronización con GitHub Issues
- Soporte para subtareas y dependencias

## Instalación

### Requisitos previos

- Node.js 18 o superior
- npm 9 o superior

### Instalar globalmente

npm install -g taskflow-cli

### Verificar la instalación

taskflow --version

## Uso

### Crear una tarea

taskflow add "Revisar pull requests" --proyecto=mi-app --prioridad=alta

### Listar tareas

taskflow list
taskflow list --proyecto=mi-app --estado=pendiente

### Marcar como completada

taskflow done 15

### Exportar a Markdown

taskflow export --formato=md --salida=tareas.md

## Configuración

Crea un archivo `.taskflowrc` en la raíz de tu proyecto:

{
  "proyectoPorDefecto": "mi-app",
  "formatoFecha": "DD/MM/YYYY",
  "github": {
    "sincronizar": true,
    "repositorio": "usuario/mi-app"
  }
}

## Contribuir

1. Haz un fork del repositorio
2. Crea una rama (`git checkout -b feature/nueva-funcionalidad`)
3. Ejecuta los tests (`npm test`)
4. Haz commit siguiendo Conventional Commits
5. Abre un Pull Request

Lee [CONTRIBUTING.md](CONTRIBUTING.md) para más detalles.

## Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo
[LICENSE](LICENSE) para más detalles.

Errores comunes al escribir un README

Estos son los errores que se repiten con más frecuencia en repositorios públicos y que hacen que los visitantes abandonen el proyecto:

No incluir descripción

Un repositorio sin descripción clara es un repositorio invisible. Si alguien llega a tu proyecto y no entiende en 5 segundos qué hace, se irá. Siempre empieza con una frase que explique el qué y el para quién.

README demasiado largo sin estructura

Un README de 500 líneas sin tabla de contenidos ni secciones claras es igual de inútil que uno vacío. Si tu documentación es extensa, considera mover partes a una carpeta docs/ y dejar el README como resumen con enlaces. Puedes usar herramientas como MkDocs o Docusaurus para la documentación técnica completa.

No incluir ejemplos de uso

Explicar qué hace un proyecto sin mostrar cómo se usa es como vender un producto sin dejar que la gente lo pruebe. Incluye siempre al menos un ejemplo básico que el usuario pueda copiar y ejecutar directamente.

Información desactualizada

Comandos que ya no funcionan, versiones antiguas o capturas de pantalla que no corresponden con la interfaz actual destruyen la confianza del usuario. Cada vez que hagas un cambio importante en el proyecto, revisa el README. Puedes añadir una tarea en tu CI/CD para verificar que los enlaces del README no estén rotos.

Ignorar los requisitos previos

Asumir que todos tienen el mismo entorno que tú es un error clásico. Si tu proyecto necesita Python 3.11, PostgreSQL 15 o una API key específica, indícalo claramente antes de los pasos de instalación.

Herramientas útiles para crear READMEs

readme.so

readme.so es un generador visual de README online. Te permite arrastrar y soltar secciones, rellenar los campos y descargar el archivo Markdown listo para usar. Es ideal si quieres empezar rápido con una estructura sólida sin tener que recordar la sintaxis.

shields.io

shields.io es el servicio estándar para generar badges dinámicos. Puedes crear badges que muestren automáticamente datos reales de tu proyecto: estado del build en GitHub Actions, versión publicada en npm, cobertura de tests, número de issues abiertas y mucho más. Solo necesitas construir la URL con los parámetros correctos.

carbon.now.sh

carbon.now.sh genera imágenes de código con resaltado de sintaxis y fondos atractivos. Es perfecto para crear capturas de pantalla de fragmentos de código que quieras incluir en tu README como imagen, especialmente útil para publicaciones en redes sociales o documentación visual.

Siguientes pasos

Una vez que tengas tu README listo, puedes:

👋 Hola! Soy Edu, me encanta crear cosas y he redactado este tutorial. Si te ha resultado útil, el mayor favor que me podrías hacer es el de compatirlo en Twitter.

para estar al día con mi contenido. 😊