Guía de Ingeniería de README y Documentación Técnica
Un marco riguroso para crear READMEs de repositorios GitHub de clase mundial, de calidad humana, que respeten el tiempo del lector, comuniquen el valor técnico con claridad y eliminen el relleno de marketing genérico.
1. La Filosofía Central: La Regla de los 30 Segundos
Los desarrolladores y usuarios no "leen" la documentación de principio a fin; la escanean a alta velocidad. Ponte en el lugar de un desarrollador cansado que acaba de tropezar con tu repositorio a las 2 a.m.
Tu README debe responder tres preguntas en menos de 30 segundos:
- ¿Qué es esto? (Una definición clara de una sola frase, sin ningún tipo de marketing).
- ¿Por qué debería importarme? (El problema del mundo real que resuelve y qué soluciones alternativas frustrantes reemplaza).
- ¿Cómo lo ejecuto ahora mismo? (Un inicio rápido de 3 pasos, copiable y pegado, con comandos probados).
2. Pautas para una Escritura Clara y con Los Pies en la Tierra
La documentación a menudo se convierte en un lenguaje corporativo inflado. Los proyectos de código abierto de alta calidad evitan este tono por completo.
2.1 El Diccionario de Palabras Prohibidas y Clichés
| ❌ Palabra de Moda / Cliché Prohibido | ✔️ Alternativa Clara y con Los Pies en la Tierra |
|---|---|
| "En el acelerado panorama digital actual..." | (Elimínalo por completo. Ve directo al problema). |
| "Transferir sin esfuerzo / integrar sin problemas..." | "Arrastra archivos desde tu navegador y aparecen en tu teléfono." |
| "Una plataforma revolucionaria y de vanguardia..." | "Un relevo personal ligero y autohospedado." |
| "Eleva tu productividad a nuevas alturas..." | "Te ahorra tener que enviarte enlaces por correo electrónico." |
| "Un testimonio del desarrollo moderno..." | (Elimínalo. Habla como un ingeniero, no como una agencia de relaciones públicas). |
| "Eliminó por completo los enormes banners de héroe..." | (Nunca te jactes de refactorizaciones internas. Indica lo que la interfaz de usuario ofrece ahora). |
| "Arquitectura de inicio de sesión web defensiva..." | "Inicio de sesión seguro usando cookies HttpOnly SameSite y tokens CSRF." |
| "Caché SWR de cero esqueleto..." | "Carga instantánea: abre tu bandeja de entrada sin pantallas en blanco." |
2.2 Reglas para una Escritura Auténtica
- La Prueba del "Café del Martes": Lee tu borrador en voz alta. ¿Suena como un ingeniero de software reflexivo que explica su herramienta favorita a un colega mientras toman un café? Si suena como un folleto de marketing corporativo, reescríbelo.
- Disciplina de Insignias: Limita las insignias a 3–6 indicadores significativos (Versión, Estado de compilación/CI, Licencia, Stack principal). No apiles 15 escudos decorativos que distraigan del proyecto.
- Sin Requisitos Previos Ocultos: Nunca escribas
docker compose uponpm startsin enumerar los requisitos previos y de dónde provienen las credenciales del entorno.
3. La Estructura de Doble Audiencia
La buena documentación une a dos audiencias distintas sin comprometer la claridad:
flowchart TD
Audience["Visitante del Repositorio"]
Audience --> HomeUser["1. Persona Normal / Usuario Cotidiano<br>(Quiere saber si esto resuelve su punto débil)"]
Audience --> Sysadmin["2. Ingeniero / Administrador de Sistemas / Desarrollador<br>(Quiere conocer la arquitectura, la seguridad y el stack)"]
HomeUser --> PlainSection["Sección '¿Por Qué Existe Esto?'<br>- Situaciones del mundo real (sin más bots de mensajería ni archivos adjuntos por correo)<br>- Flujo de trabajo conceptual de 3 pasos<br>- Beneficios de privacidad y autohospedaje"]
Sysadmin --> TechSection["Sección 'Cómo Funciona'<br>- Diagrama de arquitectura (Mermaid)<br>- Responsabilidades de los componentes<br>- Modelo de seguridad y tokens<br>- Mecánica de almacenamiento y base de datos"]
3.1 Lenguaje Sencillo para Usuarios Cotidianos
Comienza con una fricción del mundo real con la que te puedas identificar:
"¿Alguna vez te has enviado un enlace por correo electrónico, le has enviado un mensaje a un bot en Telegram o WhatsApp solo para copiar texto a tu teléfono, o has esperado a que se sincronice la nube solo para mover un solo PDF? Vault reemplaza esas soluciones alternativas con tu propio buzón de mensajes privado."
3.2 Profundidad Técnica con los Pies en la Tierra para Desarrolladores
Continúa con detalles precisos de arquitectura e implementación:
- Motor API: ASP.NET Core 10 Minimal APIs que transmiten archivos de hasta 100 MB directamente al disco con verificación SHA-256 en tiempo real (cero hinchazón de RAM).
- SPA Web: React 19 + TypeScript con cookies HttpOnly SameSite, tokens CSRF y atajos de teclado (búsqueda con
/). - Cliente Móvil: Kotlin Jetpack Compose nativo con colas de salida sin conexión de WorkManager e integración con
FileProviderde Android. - Base de Datos: PostgreSQL 18 que almacena metadatos y tokens de sesión deslizantes de 14 días.
4. Escaparates Visuales y Diseños de Interfaz de Usuario
Si tu aplicación tiene una interfaz visual (Web, Móvil o salida de CLI), muéstrala inmediatamente después del discurso introductorio.
4.1 Patrón de Tabla de Escaparate Adaptable
<table align="center" width="100%">
<tr>
<th width="33%" align="center">📱 Bandeja de Entrada Móvil</th>
<th width="33%" align="center">⚙️ Centro de Dispositivos</th>
<th width="34%" align="center">🔐 Vinculación Sin Problemas</th>
</tr>
<tr>
<td align="center" valign="top">
<img src="docs/assets/mobile-inbox.png" alt="Bandeja de Entrada Móvil" width="260px" />
<br/>
<sub><i>Caché local instantánea, búsqueda en vivo y acciones con un solo toque.</i></sub>
</td>
<!-- Columnas restantes -->
</tr>
</table>
4.2 Reglas para Capturas de Pantalla:
- Leyendas Informativas: Usa leyendas para describir lo que el usuario puede hacer en la vista, no para encadenar palabras de moda.
- Capturas de Pantalla Reales: Usa siempre capturas nítidas de la interfaz de usuario real del producto, en lugar de plantillas de maquetas genéricas con marcos de portátiles falsos.
5. Diseño de Inicio Rápido a Prueba de Fallos
Los inicios rápidos deben ser reproducibles sin necesidad de solucionar problemas.
El Inicio Rápido Estándar de 3 Pasos:
### 1. Generar Certificados y Credenciales Locales
```bash
./scripts/setup-local.sh # o ./scripts/setup-local.ps1
Qué hace esto: Genera un certificado TLS de localhost de confianza en .local/tls/ y escribe una contraseña de arranque aleatoria en .env.
2. Iniciar el Stack
docker compose up -d
3. Abrir Tu Espacio de Trabajo
Navega a https://localhost:8080 en tu navegador:
- Nombre de usuario:
[email protected](oowner) - Contraseña: La contraseña de arranque en tu archivo
.env
---
## 6. Lista de Verificación de la Estructura Estándar del README
Usa esta lista de verificación al estructurar cualquier README de repositorio técnico:
- [ ] **1. Encabezado y Título:** Logotipo / Icono, Título y un eslogan funcional de una frase.
- [ ] **2. Insignias Enfocadas:** Versión de lanzamiento, Estado de compilación, Plataformas principales, Licencia.
- [ ] **3. Por Qué Existe Esto:** El problema cotidiano, la solución y el flujo de trabajo de 3 pasos en lenguaje sencillo.
- [ ] **4. Recorrido Visual:** Capturas de pantalla de las interfaces Web, Móvil o CLI con leyendas prácticas.
- [ ] **5. Capacidades Principales:** Lista de funciones centrada en el usuario organizada por tareas reales.
- [ ] **6. Cómo Funciona (Técnico):** Diagrama de arquitectura Mermaid + desglose conciso de componentes (API, Cliente, BD, Autenticación/Seguridad).
- [ ] **7. Inicio Rápido (Docker / Local):** Requisitos previos, comandos paso a paso y ubicaciones de credenciales.
- [ ] **8. Configuración Móvil / del Cliente (si corresponde):** Enlaces de descarga directa, instrucciones de vinculación y guía de prueba en LAN.
- [ ] **9. Pruebas y Verificación Automatizadas:** Comandos para ejecutar los conjuntos de pruebas del backend y del frontend localmente.
- [ ] **10. Mapa del Repositorio y Contribuciones:** Árbol de carpetas ASCII limpio, enlace a las pautas y licencia MIT/Apache.
---
## 7. Repositorios de Código Abierto de Referencia
Inspecciona estos célebres READMEs de código abierto para inspirarte en estructura y apariencia visual:
- **`matiasingers/awesome-readme`**: Directorio seleccionado de los mejores READMEs en GitHub.
- **`othneildrew/Best-README-Template`**: El estándar de oro de la industria para plantillas de repositorios modulares y de alto impacto.
- **`charmbracelet/bubbletea` y `charmbracelet/gum`**: Escaparates de terminal excepcionales, uso de GIFs y bloques de código escaneables.
- **`supabase/supabase`**: Excelente equilibrio de doble audiencia con diagramas de arquitectura de sistema claros y una incorporación rápida.
- **`fastapi/fastapi`**: Clase magistral en inicios rápidos sin fricción, ejemplos de código reales y una propuesta de valor clara.