Cómo escribir un buen README.md

Lo primero que alguien ve en un proyecto de GitHub es su README.md. Un buen README explica en 30 segundos qué es el proyecto, cómo instalarlo y cómo usarlo. Esta guía repasa la estructura estándar, el Markdown más habitual y una plantilla para copiar.

Para escribir mientras lees, abre el editor de Markdown online: escribe a la izquierda y mira el resultado a la derecha.

¿Qué debe incluir un README?

Un README sólido suele incluir, en este orden:

  1. Nombre del proyecto y una frase de resumen: qué problema resuelve.
  2. Captura o demo: una imagen vale más que varios párrafos.
  3. Funcionalidades: de tres a seis puntos clave.
  4. Instalación: comandos para copiar y ejecutar.
  5. Uso: el ejemplo más sencillo que funcione.
  6. Configuración: variables de entorno o archivos de configuración, si los hay.
  7. Contribuir: cómo informar de errores y proponer cambios.
  8. Licencia: por ejemplo MIT o Apache-2.0.

En proyectos pequeños bastan los puntos 1, 4, 5 y 8. Lo importante es que quien llega por primera vez consiga ponerlo en marcha.

El Markdown que más usarás

Título y resumen

# Moread

> Un visor de Markdown sin instalación que nunca sube tus archivos.

Usa un único título con # y ## para las secciones. Consulta la guía de sintaxis Markdown para el resto.

Comandos de instalación en bloques de código

```bash
git clone https://github.com/you/project.git
cd project
npm install
```

Indicar el lenguaje (bash, python, javascript) activa el resaltado de sintaxis en GitHub.

Capturas de pantalla

![Pantalla principal](docs/screenshot.png)

Guarda las imágenes en una carpeta como docs/ o assets/ y usa rutas relativas para que no se rompan al mover el proyecto.

Insignias (badges)

Muchos README empiezan con insignias de versión, licencia o estado de compilación:

![License](https://img.shields.io/badge/license-MIT-green)

Quedan bien, pero con unas pocas basta.

Opciones en tablas

| Opción | Por defecto | Descripción |
| --- | --- | --- |
| `port` | `3000` | Puerto del servidor |
| `debug` | `false` | Mostrar información de depuración |

Más trucos en la guía de tablas en Markdown.

Diagramas de arquitectura con Mermaid

GitHub admite Mermaid, así que puedes dibujar diagramas directamente en el README:

flowchart LR
    A[Usuario] --> B[Frontend] --> C[API] --> D[Base de datos]

Detalles en la guía de diagramas Mermaid.

Plantilla de README (copia y pega)

# Nombre del proyecto

Una frase sobre el problema que resuelve este proyecto.

![Captura](docs/screenshot.png)

## Funcionalidades

- Funcionalidad uno
- Funcionalidad dos
- Funcionalidad tres

## Instalación

```bash
npm install your-package
```

## Uso

```javascript
import { hello } from 'your-package';
hello('world');
```

## Configuración

| Opción | Por defecto | Descripción |
| --- | --- | --- |
| `option` | `true` | Qué hace esta opción |

## Contribuir

Se agradecen issues y pull requests.

## Licencia

MIT

Pega la plantilla en el editor online, complétala y descárgala como README.md con Ctrl + S.

Consejos para un README mejor

  • Empieza por «cómo ponerlo en marcha»: la mayoría solo quiere instalarlo y probarlo.
  • Comandos fáciles de copiar: no mezcles explicaciones en las líneas de comando.
  • Mantenlo al día: si cambia el código, actualiza el README.
  • Añade un índice en los README largos.
  • Ofrece traducciones como README.es.md y enlázalas al principio.

Al terminar, arrastra README.md a Moread para comprobar que títulos, tablas y diagramas se ven bien antes de hacer push.