Llevas meses aprendiendo a programar y en algún momento te preguntas qué tiene que tener tu código para que alguien externo lo tome en serio. No un recruiter — cualquier persona: un compañero, un profesor, alguien que revise tu GitHub.
Aquí está el problema real: la mayoría aprende a escribir código que funciona, pero no aprende a presentarlo. Y un proyecto que no se entiende desde fuera parece abandonado aunque funcione perfectamente.
Qué hace que un proyecto parezca serio
Dos repos en GitHub con el mismo código. Uno tiene un README de tres líneas. El otro explica qué hace el proyecto, cómo ejecutarlo y qué decisiones técnicas tomaste. Son el mismo código, pero no parecen lo mismo.
Lo que diferencia un portfolio que da confianza de uno que no:
- Se entiende qué hace cada proyecto sin leer el código
- Se puede ejecutar localmente siguiendo las instrucciones
- Hay al menos una URL donde verlo funcionando
- El código está organizado, no todo en un archivo
Ninguno de estos puntos requiere saber más tecnología. Requieren dedicar tiempo a documentar lo que ya tienes.
Qué proyectos construir
El error más habitual es acumular proyectos de tutoriales: la calculadora, el todo-list, el clon de Netflix. No hay nada malo en hacerlos para aprender, pero no demuestran que puedes resolver un problema propio.
Un proyecto propio, aunque sea simple, demuestra algo diferente: que eres capaz de identificar un problema, diseñar una solución y llevarla a cabo sin que nadie te diga paso a paso qué hacer.
Tipos de proyectos que tienen más contexto:
- Algo que usas tú mismo: una app para gestionar tus gastos, un tracker de hábitos, un organizador de recetas
- Algo con datos reales: conectado a una API pública, con datos que cambian
- Algo completo: no solo el frontend — con backend aunque sea básico, con base de datos aunque sea SQLite
No necesitas los tres a la vez. Un proyecto propio bien documentado vale más que seis proyectos de tutoriales sin README.
Cómo documentar un proyecto
El README es lo primero que ve cualquiera que llega a tu repositorio. Si no hay README, la impresión es que el proyecto está abandonado o que es un ejercicio privado.
Un README útil tiene estas partes:
Descripción en una frase
Qué hace el proyecto. Sin jerga técnica, sin mencionar las tecnologías todavía. Solo qué problema resuelve o qué hace.
# Gestor de gastos personales
# App web para registrar gastos por categoría y ver en qué
# se va el dinero cada mes.Captura o demo
Una imagen del proyecto funcionando o un enlace a la versión desplegada. Si no hay ninguna de las dos, nadie sabe cómo se ve sin clonarlo y ejecutarlo ellos mismos — y casi nadie lo va a hacer.
Cómo ejecutarlo
Los comandos exactos para clonar, instalar dependencias y arrancar el proyecto. Incluye la versión de Node, PHP o lo que uses si es relevante. Pruébalo en una carpeta nueva antes de publicarlo.
# Clonar el repositorio
git clone https://github.com/tu-usuario/gastos-personales
# Instalar dependencias
npm install
# Arrancar en local
npm run devDecisiones técnicas
Por qué elegiste esas tecnologías. No hace falta que sea largo — dos o tres líneas explicando "usé SQLite porque no necesitaba un servidor de base de datos para este proyecto" dice mucho más que una lista de tecnologías.
Lo que no necesita el README:
- Una lista de todo lo que aprendiste haciéndolo
- Disculpas por el código ("sé que podría mejorar...")
- La historia de por qué empezaste el proyecto
Desplegar los proyectos
Un proyecto que solo funciona en tu máquina no existe para nadie más. Desplegar no tiene que ser complicado ni caro.
- Frontend estático: Netlify o Vercel, gratis, en menos de 5 minutos conectando el repositorio de GitHub
- Backend Node.js o Python: Railway o Render, también gratuitos en el tier básico
- Base de datos: Neon para PostgreSQL, MongoDB Atlas para MongoDB, ambos con plan gratuito
Si ya tenemos un post sobre hosting gratuito, está todo explicado ahí: Hosting gratis 2025.
Organizar el código
No hay que seguir una arquitectura perfecta, pero sí hay cosas básicas que marcan la diferencia:
- No tener todo en un solo archivo de 500 líneas
- Nombres de variables y funciones que se entienden sin comentarios
- Las credenciales y claves de API en variables de entorno, nunca en el código
- Un
.gitignoreque excluyanode_modules,.envy archivos del sistema
El último punto es importante. Subir el archivo .env con claves reales a GitHub es un error que pasa más de lo que parece y que puede tener consecuencias reales. Si no sabes cómo funciona, tenemos un post específico: Variables de entorno: la regla de oro.
GitHub: el historial importa
Un repositorio con un solo commit de "subir proyecto" no cuenta la historia de cómo lo construiste. Los commits frecuentes con mensajes descriptivos muestran que trabajas de forma ordenada.
No hace falta que los mensajes sean perfectos. Pero "añadir validación del formulario de contacto" es mejor que "cambios" o "fix".
Tampoco hace falta hacer commit de cada línea. Un commit por funcionalidad o por sesión de trabajo es suficiente para que el historial cuente algo.
Lo que sí vale la pena tener en GitHub:
- Repositorios con README completo en todos los proyectos
- Historial de commits que muestra progreso real
- Proyectos desplegados con la URL en la descripción del repositorio
- Un perfil README que explique en qué estás trabajando
El perfil README es el archivo especial que aparece en tu página de GitHub. Si creas un repositorio con tu mismo nombre de usuario y le añades un README, GitHub lo muestra en tu perfil. Es opcional, pero da una buena primera impresión.