# Escribir un README que sirva

URL canónica: https://missyera.com/guias/git-desde-cero/escribir-un-readme/
Última actualización: 2026-11-17
Autora: Gera Flores (Miss Yera)

> **Respuesta corta**
>
> <strong>Un README sirve si alguien que no conoce el proyecto llega solo hasta verlo funcionando.</strong> Eso son cuatro secciones: qué hace en una frase, qué necesitas instalado, cómo se instala y cómo se ejecuta, con los comandos copiables. Todo lo demás (capturas, licencia, cómo contribuir) es bienvenido pero va después. Se escribe en markdown, que son cinco símbolos, y el archivo se llama <code>README.md</code> en la raíz.

Capítulo 18 de 33 del libro [Git desde cero](https://missyera.com/guias/git-desde-cero.md).

El README es lo primero que se ve al entrar a un repositorio, y en la mayoría de proyectos es también lo único que se lee. Es tu portada 🎯

Y hay una prueba muy simple para saber si el tuyo sirve: dáselo a alguien que no conoce el proyecto y mira si llega solo hasta la primera salida en pantalla. Si tiene que preguntarte algo, falta eso en el README.

## Markdown en cinco símbolos

El `.md` del final significa markdown, que es texto normal con unas marcas. Estas cinco resuelven el 95%:

| Escribes | Se ve |
|---|---|
| `# Título` | Un título grande |
| `## Sección` | Un título mediano |
| `**negrita**` | En negrita |
| `- item` | Una lista con viñetas |
| Tres tildes invertidas | Un bloque de código |

## Las cuatro secciones que no pueden faltar

Vamos a escribir el README del proyecto de ventas, entero, y a mirarlo:

```bash
mkdir ventas-miss-yera
cd ventas-miss-yera
git init -q
printf 'ciudad,monto\nLima,1200\nArequipa,890\n' > ventas.csv
printf 'pandas\n' > requirements.txt
cat > README.md <<'FIN'
# Ventas Miss Yera

Calcula el total de ventas por ciudad a partir de un CSV.

## Necesitas

- Python 3.11 o superior

## Instalar

```
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Usar

```
python3 total.py ventas.csv
```

Devuelve el monto total por ciudad, ordenado de mayor a menor.
FIN
git add .
git commit -q -m "Se escribe el README del proyecto de ventas"
cat README.md
```

```text
# Ventas Miss Yera

Calcula el total de ventas por ciudad a partir de un CSV.

## Necesitas

- Python 3.11 o superior

## Instalar

```
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Usar

```
python3 total.py ventas.csv
```

Devuelve el monto total por ciudad, ordenado de mayor a menor.
```

Fíjate en el orden: **qué hace, qué necesitas, cómo se instala, cómo se usa**. Nadie llegó al proyecto para leer sobre arquitectura modular escalable; llegó para hacerlo andar 🏃‍♀️

## Lo que va después, si quieres

- Un ejemplo de la salida, que vale por tres párrafos.
- La licencia, que vimos en 16.
- Cómo contribuir, si esperas que alguien lo haga.
- A quién escribir si algo falla.

Y una cosa que no va: la lista de "tecnologías utilizadas" con veinte logos. A quien va a usarlo le da igual, y a quien va a contratarte también 🙃

## Ampliarlo sin romperlo

```bash
cat >> README.md <<'FIN'

## Ejemplo de salida

```
Lima        1200
Arequipa     890
```

## Licencia

MIT
FIN
git add README.md
git commit -q -m "Se agregan el ejemplo de salida y la licencia al README"
tail -12 README.md
git log --oneline
```

```text
Devuelve el monto total por ciudad, ordenado de mayor a menor.

## Ejemplo de salida

```
Lima        1200
Arequipa     890
```

## Licencia

MIT
755555e Se agregan el ejemplo de salida y la licencia al README
081de70 Se escribe el README del proyecto de ventas
```

## El README de tu perfil

Hay un truco que casi nadie conoce y que a mí me parece de los más útiles para quien está armando su portafolio: si creas un repositorio **con el mismo nombre que tu usuario** y le pones un `README.md`, GitHub lo muestra en tu perfil.

```bash
cd ..
mkdir mi-usuario
cd mi-usuario
git init -q
cat > README.md <<'FIN'
## Hola, soy Gera

Trabajo con datos e IA en empresas de consumo masivo.

- Analizo ventas por ciudad y canal
- Automatizo reportes que antes se hacían a mano
- Escribo en missyera.com
FIN
git add README.md
git commit -q -m "README del perfil"
cat README.md
```

```text
## Hola, soy Gera

Trabajo con datos e IA en empresas de consumo masivo.

- Analizo ventas por ciudad y canal
- Automatizo reportes que antes se hacían a mano
- Escribo en missyera.com
```

Eso es lo que ve quien entra a tu perfil antes de mirar ningún proyecto. Si estás buscando trabajo con datos, ese archivo trabaja para ti todos los días 💼

La trampa

Publicas tu analizador de ventas con un README bonito que explica qué hace, para qué sirve y quién lo escribió. Nadie lo usa.

```
# Analizador de ventas

Herramienta de análisis de ventas multicanal desarrollada
con un enfoque modular y escalable para el sector retail.

## Autor
Yo

## Licencia
MIT
```

**Qué está mal**

No hay una sola línea que diga cómo se pone en marcha 🤔

Quien llega a tu README ya sabe más o menos qué hace, porque para eso entró. Lo que no sabe es qué escribir en la terminal para verlo funcionando, y si en treinta segundos no lo encuentra, se va al siguiente proyecto.

Las tres cosas que no pueden faltar son **qué necesito instalado, cómo lo instalo y cómo lo ejecuto**, con los comandos copiables. Todo lo demás es decoración.

La prueba que uso: dárselo a alguien que no conoce el proyecto y ver si llega solo hasta la primera salida en pantalla.

## Comprueba que se entendió

Comprueba que lo tienes

Tienes cinco minutos para mejorar un README. ¿Qué agregas primero?

- Los comandos exactos para instalarlo y ejecutarlo
- Una descripción más completa de qué hace el proyecto
- Una lista de las tecnologías que usaste
- Un logo y unas insignias de colores

## Ejercicios

**1. Escribe el esqueleto**

Crea el proyecto del reporte por canal con un README de cuatro secciones.

```bash
cd ..
mkdir reporte-canales
cd reporte-canales
git init -q
printf 'canal,monto\nBodegas,4200\n' > canales.csv
cat > README.md <<'FIN'
# Reporte por canal

Resume las ventas por canal a partir de un CSV.

## Necesitas
- Python 3.11

## Instalar
```
pip install pandas
```

## Usar
```
python3 reporte.py canales.csv
```
FIN
git add .
git commit -q -m "README del reporte por canal"
cat README.md
```

```text
# Reporte por canal

Resume las ventas por canal a partir de un CSV.

## Necesitas
- Python 3.11

## Instalar
```
pip install pandas
```

## Usar
```
python3 reporte.py canales.csv
```
```

Cuatro secciones y cabe en una pantalla. Así se lee.

**2. Agrega el ejemplo de salida**

Un ejemplo real explica más que un párrafo.

```bash
cat >> README.md <<'FIN'

## Ejemplo
```
Bodegas   4200
```
FIN
git add README.md
git commit -q -m "Se agrega el ejemplo de salida"
tail -6 README.md
```

```text
```

## Ejemplo
```
Bodegas   4200
```
```

Quien lo lea ya sabe qué esperar antes de instalar nada.

**3. Cuenta cuántas líneas tiene**

Un README de doscientas líneas no lo lee nadie.

```bash
wc -l README.md
```

```text
21 README.md
```

Entre veinte y cincuenta líneas es un buen sitio donde estar.

**4. Comprueba que están las secciones clave**

Lista los títulos del archivo.

```bash
grep "^#" README.md
```

```text
# Reporte por canal
## Necesitas
## Instalar
## Usar
## Ejemplo
```

Este grep es mi revisión rápida: si no veo "Instalar" y "Usar", falta lo importante.

**5. Enlaza otro archivo del proyecto**

En markdown, un enlace es texto entre corchetes y destino entre paréntesis.

```bash
printf 'MIT License\n' > LICENSE
cat >> README.md <<'FIN'

Ver la [licencia](LICENSE).
FIN
git add .
git commit -q -m "Se enlaza la licencia desde el README"
tail -2 README.md
```

```text
Ver la [licencia](LICENSE).
```

GitHub convierte ese enlace en un clic que lleva al archivo.

**6. Arma el README de tu perfil**

El repositorio que se llama igual que tu usuario.

```bash
cd ..
mkdir perfil
cd perfil
git init -q
cat > README.md <<'FIN'
## Hola

- Analizo ventas por ciudad y canal
- Automatizo reportes
FIN
git add README.md
git commit -q -m "README del perfil"
cat README.md
```

```text
## Hola

- Analizo ventas por ciudad y canal
- Automatizo reportes
```

Es el único repositorio de GitHub que se muestra fuera de su propia página 🪪

**7. Pide un archivo que no escribiste**

Intenta mostrar un README que no existe en esta carpeta.

```bash
cat CONTRIBUTING.md
```

```
cat: CONTRIBUTING.md: No such file or directory
```

"No such file or directory" es el error más común de la terminal, y casi siempre significa que estás en otra carpeta 📁

## Lo que te llevas

**Qué hace, qué necesitas, cómo se instala y cómo se usa. Si alguien llega solo hasta la primera salida, tu README sirve.**

## Seguir leyendo

- Anterior: [Publicar lo tuyo en GitHub](https://missyera.com/guias/git-desde-cero/publicar-en-github.md)
- Siguiente: [Publicar una web gratis con GitHub Pages](https://missyera.com/guias/git-desde-cero/publicar-una-web.md)

## Contacto

- Diagnóstico de 30 minutos con Miss Yera: https://calendly.com/soymissyera/reunion-con-yera
- Correo: hola@missyera.com
- Esta página en HTML: https://missyera.com/guias/git-desde-cero/escribir-un-readme/
- Índice de todas las páginas en texto: https://missyera.com/llms-index.txt
