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:
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
# 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
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
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.
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
## 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 analisis 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.
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
# 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.
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
``` ## 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.
wc -l README.md
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.
grep "^#" README.md
# 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.
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
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.
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
## 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.
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.