Cómo escribir un buen README (con ejemplo y generador gratis)

Un README es lo primero que la gente ve al abrir tu proyecto. Tiene que responder rápido a tres preguntas: qué es esto, cómo empiezo y si puedo usarlo. Si no lo hace, la mayoría se va, por muy bueno que sea el código. Y dentro de seis meses, quien lo lea puede que seas tú.

Esta guía explica qué debe llevar un buen README y en qué orden, con un ejemplo completo. Si prefieres no empezar con una página en blanco, el generador de README gratuito lo escribe a partir de un formulario corto.

¿Qué es un archivo README?

Es un archivo de texto en la carpeta principal de un proyecto, normalmente llamado README.md. El .md indica que está escrito en Markdown, una forma sencilla de dar formato al texto. GitHub, GitLab y sitios parecidos lo muestran automáticamente en la portada del proyecto, así que es como su página de inicio.

Qué poner en un README, en orden

1. Nombre y descripción en una línea. Di qué hace, no cómo está construido. «Guarda tus recetas favoritas y encuéntralas en segundos» es mejor que «Una aplicación en React y Node.js».
2. Insignias (opcional). Pequeñas etiquetas con la licencia, la versión actual o el número de estrellas.
3. Índice. Merece la pena cuando el README ocupa más de una pantalla.
4. Acerca de. Dos o tres frases: qué problema resuelve y para quién es.
5. Características. Una lista corta, para ver de un vistazo si hace lo que se necesita.
6. Instalación. Los comandos exactos, listos para copiar. Pruébalos tú en un equipo limpio: los pasos que faltan son el problema más habitual de los README.
7. Uso. El ejemplo más pequeño que funcione. Un fragmento de código corto dice más que una explicación larga.
8. Captura de pantalla. Si tiene interfaz, una imagen ahorra un párrafo.
9. Contribuir. Cómo pueden ayudar otras personas, por ejemplo abriendo una incidencia antes de enviar un cambio.
10. Licencia y autor. Qué se puede hacer con tu trabajo y quién lo hizo.

Un proyecto pequeño no lo necesita todo. Lo esencial es nombre, descripción, instalación, uso y licencia.

Un ejemplo completo de README

Aquí tienes un README corto para un proyecto pequeño, listo para adaptar:

# recipe-box

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Save your favourite recipes and find them again in seconds.

## Table of contents

- [About](#about)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [License](#license)

## About

A small app for people with too many recipes in too many places.
Everything is stored on your own computer.

## Features

- Search by ingredient
- Works offline
- Export to PDF

## Installation

```bash
git clone https://github.com/janedoe/recipe-box.git
cd recipe-box
npm install
```

## Usage

Start the app and open http://localhost:3000:

```bash
npm start
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

© 2026 Jane Doe

Cómo crear uno con el generador

1. Abre el generador de README. Haz clic en Ejemplo para ver uno relleno, o en Borrar para empezar con el tuyo.
2. Rellena el Nombre del proyecto y la Descripción en una línea. Añade el Repositorio de GitHub como propietario/nombre y el Paquete npm si los tienes: las insignias y los enlaces los usan.
3. Rellena las secciones que quieras, como Características (una por línea), Instalación y Uso. Las que dejes vacías no se incluyen.
4. Marca o desmarca Insignias e Índice, y elige una Licencia.
5. Revisa el resultado en Vista previa, o mira el código en Markdown, y haz clic en Copiar o Descargar. El archivo descargado lleva un nombre con fecha, así que cámbialo a README.md.

Puedes escribir el README en inglés, español, alemán o francés: Idioma del README define los títulos y las frases estándar, y lo que escribes se queda tal cual. Las insignias aparecen como recuadros con su nombre en la vista previa, porque no carga imágenes de otros sitios; en GitHub se ven con normalidad.

¿Qué licencia elijo?

Sin licencia, los demás no tienen un derecho claro a usar tu código, aunque sea público. Estas son las opciones del generador, en resumen. Es información general, no asesoramiento legal.

• MIT e ISC: cortas y permisivas. Se puede hacer casi de todo si se conserva tu aviso de copyright.
• Apache-2.0: también permisiva, con una concesión expresa de patentes.
• BSD-3-Clause: permisiva, y nadie puede usar tu nombre para promocionar sus productos sin permiso.
• MPL-2.0: los cambios en tus archivos deben compartirse, pero esos archivos pueden formar parte de un proyecto cerrado mayor.
• GPL-3.0: todo lo que se distribuya basado en tu código también debe ser de código abierto bajo la GPL.

Un paso que el README no hace por ti: la sección Licencia solo menciona la licencia. Añade también el texto completo en un archivo llamado LICENSE. En GitHub, elige Add file, escribe LICENSE como nombre y elige una plantilla.

Errores habituales en un README

• Empezar por la tecnología. Di primero qué hace por quien lo lee.
• Comandos que no funcionan. Ejecútalos tú y actualízalos cuando cambie el proyecto.
• Dar cosas por sabidas. Indica qué hay que instalar antes, como Node.js o Python, y qué versión.
• Un muro de texto. Usa títulos, listas cortas y bloques de código.

Más herramientas de Markdown

• Generador de tablas Markdown: crea tablas para tu README en una cuadrícula o pégalas desde Excel.
• Markdown a HTML: convierte tu README en una página web. Consulta también cómo convertir Markdown a HTML.

Preguntas frecuentes

¿Tiene que llamarse README.md?

Sí, si quieres que GitHub y sitios parecidos lo muestren automáticamente. Ponlo en la carpeta principal del proyecto.

¿Se sube lo que escribo?

No. El README se crea en tu navegador, así que lo que escribes nunca sale de tu dispositivo. Rellenar el formulario es gratis; copiar o descargar el resultado cuenta como un uso de tu cupo diario.

¿Puedo cambiar el README más tarde?

Sí. Es un archivo de texto: edítalo con cualquier editor o directamente en GitHub. Actualízalo cuando cambien la instalación o el uso.