Cómo documentar un proyecto en GitHub para que un recruiter lo entienda en 60 segundos: README, demo y commits

Resumen ejecutivo

• Un recruiter no técnico le dedica poco tiempo a cada repo: tu README tiene que explicar en un minuto qué problema resuelve el proyecto, cómo se ve y con qué está hecho.

• La estructura que funciona: título y frase de valor, demo (GIF o link), stack, cómo correrlo, decisiones técnicas y próximos pasos.

• Cuidá lo que no se ve en el README: historial de commits prolijo, nada de secrets ni datasets enormes, y un repo fijado en tu perfil.

• Incluye una plantilla de README lista para copiar para un proyecto junior de frontend o de data.

Tenés el proyecto terminado, funciona y lo subiste a GitHub. El problema es que, para quien revisa tu postulación, un repo sin documentación es una lista de carpetas que no dice nada. La primera persona que abre ese link suele ser un recruiter que no va a leer tu código: va a buscar en segundos si el proyecto se entiende, si se ve profesional y si tiene relación con el puesto. Si no lo encuentra, cierra la pestaña.

Por qué ahora: en las búsquedas junior de tecnología el portfolio pesa cada vez más, y casi todas las guías se quedan en «subí proyectos a GitHub». El paso que falta es documentar el repo para que una persona no técnica entienda tu trabajo y lo pase al equipo. Si todavía estás eligiendo qué subir, empezá por esta guía de proyectos de GitHub que te consiguen trabajo y volvé acá para documentarlos.

Qué mira un recruiter cuando abre tu repo

En el primer minuto se responden cuatro preguntas:

1. ¿Qué es esto? Una frase que explique el proyecto sin jerga.

2. ¿Funciona? Una demo visible: un GIF, capturas o un link desplegado.

3. ¿Con qué está hecho? El stack, para compararlo con el aviso de empleo.

4. ¿Lo hizo esta persona y lo entiende? Decisiones técnicas explicadas con tus palabras y un historial de commits real.

Según la documentación oficial de GitHub sobre README, el archivo README es lo primero que ve cualquier visitante del repositorio y debería explicar qué hace el proyecto, por qué es útil y cómo empezar a usarlo. Ese es exactamente el orden que necesita un recruiter.

La estructura de un README que se lee en 60 segundos

1. Título y frase de valor

Nada de «proyecto-final-v2». Poné un nombre claro y una línea que diga qué problema resuelve: «App para organizar gastos compartidos entre amigos» se entiende mejor que «App de finanzas con React».

2. Demo arriba de todo

Un GIF de 10 a 20 segundos mostrando el flujo principal, o un link a la versión desplegada (GitHub Pages, Vercel, Netlify o similar). Si es un proyecto de data, una captura del dashboard o del gráfico final. Es lo que más tiempo de atención compra.

3. Stack

Una lista corta: lenguaje, framework, base de datos, herramientas de despliegue. Usá los mismos nombres que aparecen en los avisos (React, Node.js, SQL, pandas), así el recruiter hace el match sin esfuerzo.

4. Cómo correrlo

Los pasos exactos para instalarlo y ejecutarlo en local. Esta parte es para el equipo técnico que revisa después: si los pasos fallan, el proyecto pierde puntos.

5. Decisiones técnicas

Dos o tres bullets explicando por qué elegiste algo: «Usé SQLite porque el proyecto no necesitaba un servidor de base de datos», «Separé la lógica en servicios para poder testearla». Es la sección que demuestra criterio y la que más se conversa en una entrevista técnica.

6. Próximos pasos

Qué mejorarías si tuvieras más tiempo. Muestra que sabés detectar limitaciones, algo muy valorado en perfiles junior.

Plantilla de README lista para copiar

Adaptala a tu proyecto. Funciona tanto para frontend como para data:

# Nombre del proyecto

Una frase: qué problema resuelve y para quién.

![Demo](docs/demo.gif)
Demo online: https://tu-proyecto.vercel.app

## Stack
- Frontend: React + Vite
- Estilos: CSS Modules
- Datos: API pública de ...
(Para data: Python, pandas, SQL, Looker Studio)

## Cómo correrlo
1. git clone https://github.com/tu-usuario/tu-proyecto
2. npm install   (o: pip install -r requirements.txt)
3. npm run dev   (o: python main.py)

## Decisiones técnicas
- Elegí ... porque ...
- Separé ... para ...

## Qué aprendí
- ...

## Próximos pasos
- Agregar tests
- Mejorar accesibilidad

## Contacto
Tu nombre · LinkedIn · Portfolio

# Nombre del proyecto

Una frase: qué problema resuelve y para quién.

![Demo](docs/demo.gif)
Demo online: https://tu-proyecto.vercel.app

## Stack
- Frontend: React + Vite
- Estilos: CSS Modules
- Datos: API pública de ...
(Para data: Python, pandas, SQL, Looker Studio)

## Cómo correrlo
1. git clone https://github.com/tu-usuario/tu-proyecto
2. npm install   (o: pip install -r requirements.txt)
3. npm run dev   (o: python main.py)

## Decisiones técnicas
- Elegí ... porque ...
- Separé ... para ...

## Qué aprendí
- ...

## Próximos pasos
- Agregar tests
- Mejorar accesibilidad

## Contacto
Tu nombre · LinkedIn · Portfolio

# Nombre del proyecto

Una frase: qué problema resuelve y para quién.

![Demo](docs/demo.gif)
Demo online: https://tu-proyecto.vercel.app

## Stack
- Frontend: React + Vite
- Estilos: CSS Modules
- Datos: API pública de ...
(Para data: Python, pandas, SQL, Looker Studio)

## Cómo correrlo
1. git clone https://github.com/tu-usuario/tu-proyecto
2. npm install   (o: pip install -r requirements.txt)
3. npm run dev   (o: python main.py)

## Decisiones técnicas
- Elegí ... porque ...
- Separé ... para ...

## Qué aprendí
- ...

## Próximos pasos
- Agregar tests
- Mejorar accesibilidad

## Contacto
Tu nombre · LinkedIn · Portfolio

# Nombre del proyecto

Una frase: qué problema resuelve y para quién.

![Demo](docs/demo.gif)
Demo online: https://tu-proyecto.vercel.app

## Stack
- Frontend: React + Vite
- Estilos: CSS Modules
- Datos: API pública de ...
(Para data: Python, pandas, SQL, Looker Studio)

## Cómo correrlo
1. git clone https://github.com/tu-usuario/tu-proyecto
2. npm install   (o: pip install -r requirements.txt)
3. npm run dev   (o: python main.py)

## Decisiones técnicas
- Elegí ... porque ...
- Separé ... para ...

## Qué aprendí
- ...

## Próximos pasos
- Agregar tests
- Mejorar accesibilidad

## Contacto
Tu nombre · LinkedIn · Portfolio

Si querés profundizar en la redacción de cada sección, tenemos una guía específica sobre cómo escribir el README de un proyecto de portfolio.

Commits: el historial también cuenta una historia

Quien revisa tu repo con ojo técnico mira el historial. Un único commit que dice «subo todo» genera dudas: ¿lo hiciste vos?, ¿cómo trabajás? Algunas buenas prácticas:

• Commits chicos y con mensaje claro: «Agrega validación al formulario de registro» en lugar de «cambios».

• Un formato consistente: la convención Conventional Commits (feat, fix, docs, refactor) es simple y muy usada en equipos reales.

• Ramas para funcionalidades grandes y merges ordenados, aunque trabajes solo. Simula cómo trabajarías en equipo.

• No reescribas todo el historial antes de postular. Un historial real con algunos tropiezos es más creíble que uno perfecto creado en un día.

Qué no subir nunca a un repo público

• Secrets y credenciales: claves de API, contraseñas, tokens. Usá variables de entorno y un archivo .env.example con valores de ejemplo. GitHub tiene escaneo de secretos que alerta cuando detecta credenciales, pero lo mejor es que nunca lleguen al repo.

• Datasets enormes: subí una muestra chica y explicá en el README de dónde se descarga el dataset completo.

• Carpetas generadas: node_modules, entornos virtuales, archivos de build. Configurá un .gitignore desde el primer commit.

• Datos personales reales de clientes o usuarios, aunque sea un proyecto de práctica.

Cómo enlazar el repo desde tu CV y LinkedIn

• Fijá tus 3 a 6 mejores repos en tu perfil de GitHub y escribí un README de perfil que te presente en dos líneas.

• En el CV, linkeá el proyecto, no solo el perfil: «Gestor de gastos compartidos (React, Node.js) · demo · repo».

• En LinkedIn, usá la sección Destacados con el link a la demo y una frase de lo que resolviste.

• Elegí los proyectos según el aviso: si buscás frontend, que el primero sea de frontend.

Para armar el resto del portfolio alrededor de estos repos, mirá cómo armar un portfolio de programador que consiga entrevistas.

Checklist final antes de mandar el link

• El README explica el proyecto en una frase.

• Hay una demo visible arriba de todo.

• El stack coincide con lo que pide el aviso.

• Los pasos para correrlo funcionan en una máquina limpia.

• No hay secrets, datasets pesados ni carpetas generadas.

• El repo está fijado en tu perfil y enlazado desde el CV.

Curso recomendado de Coderhouse

Si querés construir proyectos que valga la pena documentar, la Carrera de Desarrollo Full Stack te lleva de punta a punta con React, JavaScript y Node.js, trabajando con Git y proyectos para tu portfolio. Si recién empezás, el Curso de Desarrollo Web es un buen primer paso: HTML, CSS y versionado con Git y GitHub.

Preguntas frecuentes

¿El README tiene que estar en inglés o en español? Si te postulás a empresas locales, el español alcanza. Si apuntás a empresas del exterior, escribilo en inglés o sumá una versión en ambos idiomas.

¿Cuántos proyectos conviene tener documentados? Entre tres y seis bien documentados valen más que veinte repos vacíos. Priorizá calidad y relación con el puesto.

¿Cómo hago un GIF de demo? Grabá la pantalla con una herramienta gratuita, recortá el flujo principal a menos de 20 segundos y exportalo como GIF o como video corto enlazado desde el README.

¿Sirve subir proyectos hechos siguiendo un tutorial? Sí, siempre que agregues algo propio (una funcionalidad nueva, otro dataset, mejoras de diseño) y lo expliques en la sección de decisiones técnicas.