El Primer Día Del Nuevo Desarrollador

Lunes 9am. Alex se une al equipo de ingeniería.

Lead Developer: “¡Bienvenido Alex! Para entender nuestra arquitectura, empieza leyendo la documentación.”

Alex abre Notion.

Búsqueda: “Authentication”

Resultados encontrados: 8 documentos

  1. RFC-042: Arquitectura de Autenticación (creado hace 8 meses)
  2. Spec Técnica: Implementación SSO (creado hace 6 meses)
  3. Documentación API Auth v2 (creado hace 4 meses)
  4. Migración JWT → OAuth2 (creado hace 3 meses)
  5. Guía: Cómo autenticar usuarios (creado hace 2 meses)
  6. Auth System Overview [DRAFT] (creado hace 1 mes)
  7. Authentication Best Practices (creado hace 2 semanas)
  8. Auth Quick Start (creado ayer)

Alex, perplejo:

“¿Cuál debo leer? ¿Cuál está actualizado?”

Abre RFC-042 (el más antiguo).

# RFC-042: Arquitectura de Autenticación

## Status: Approved ✅

Implementaremos JWT tokens para autenticación.

### Arquitectura:
- Backend: Node.js + Express + JWT
- Tokens almacenados en localStorage
- Duración: 24h
- Sin refresh tokens (para simplificar)

Alex lee todo el documento (30 minutos).

Luego, abre el código actual:

// auth.service.ts
export class AuthService {
  // Using OAuth2 with refresh tokens
  async login(provider: 'google' | 'microsoft') {
    return this.oauth2Provider.authenticate(provider);
  }
}

Alex, confundido:

“¡El doc dice JWT, el código hace OAuth2! El doc dice sin refresh tokens, el código los tiene. El doc dice localStorage, el código usa httpOnly cookies. ¡Nada coincide!”

Le pregunta al Lead Developer:

Alex: “¿El doc RFC-042 dice que usamos JWT, pero el código hace OAuth2?”

Lead Dev: “Ah sí, cambiamos hace 4 meses. Mira mejor el doc ‘Migración JWT → OAuth2’.”

Alex: “¿Pero cuál es la versión actual?”

Lead Dev: “Eh… buena pregunta. ¿Tal vez el ‘Auth System Overview’? ¿O el ‘Quick Start’? De hecho, no estoy seguro. Lee el código, será más fiable.”

Resultado: Alex pasó 2 horas leyendo documentación obsoleta para finalmente aprender leyendo el código.

Versiones múltiples: Nadie sabe cuál es correcta

El Problema De La Documentación Muerta

La mayoría de equipos tech crean documentación. Luego muere lentamente, sin que nadie se dé cuenta.

Los Cinco Síntomas De La Documentación Muerta

1. Documentación Obsoleta (Desconectada Del Código Real)

El Escenario: Escribes una spec técnica hermosa en Notion hace 6 meses. El código evoluciona. La spec queda congelada.

Cronología típica:

Mes 1: Spec creada, perfectamente alineada con el código.

Mes 2: Pequeño cambio en el código (añadido un parámetro). Spec no actualizada (“lo haré luego”).

Mes 3: Refactoring mayor (cambio de arquitectura). Spec no actualizada (“muy ocupado, deadline”).

Mes 4: Nuevo miembro lee la spec, no entiende por qué el código es diferente.

Mes 6: La spec está oficialmente obsoleta. Nadie la lee más. Se convierte en un artefacto histórico.

El Problema:

Resultado Real: Un estudio interno en una scale-up tech de 50 personas reveló que el 73% de su documentación Confluence tenía más de 6 meses y ya no correspondía al código actual.

Cronología de la obsolescencia de documentación en 6 meses

2. Versiones Múltiples (Nadie Sabe Cuál Es Correcta)

El Escenario: Buscas “How does authentication work?” en Notion.

Encuentras:

Pregunta: ¿Cuál es la correcta?

Respuesta: Ni idea.

El Problema:

Escenario Real:

Desarrollador 1: “Lee el doc ‘Auth v2 FINAL’.”

Desarrollador 2: “No, ese está obsoleto. Lee ‘Auth Overview Updated’.”

Desarrollador 3: “Espera, el más reciente es ‘Authentication Guide’ creado la semana pasada.”

Lead Developer: “Honestamente, solo lee el código.”

3. Docs Contradictorios (Cada Doc Dice Algo Diferente)

El Escenario: Tres documentos diferentes describen la misma feature. Cada uno dice algo ligeramente diferente.

Doc A (Notion): “Los tokens expiran después de 1 hora.”

Doc B (Confluence): “Los tokens expiran después de 24 horas.”

Código actual: TOKEN_EXPIRY = 12 * 60 * 60 (12 horas)

Ninguno es correcto.

El Problema:

Ejemplo Real:

Un desarrollador implementa una feature basada en Doc A (“tokens 1h”). QA prueba basándose en Doc B (“tokens 24h”). El código hace 12h. Todos piensan que hay un bug, pero es solo que los docs mienten.

4. “Actualizaremos El Doc Después” (Spoiler: Nunca Se Hace)

El Escenario:

Viernes 5pm, fin de sprint.

Dev: “Terminé la feature SSO.”

Lead: “¡Genial! ¿Actualizaste la documentación?”

Dev: “Eh… no, no tuve tiempo. Lo haré el lunes.”

Lunes por la mañana.

Dev: (3 nuevas issues asignadas, 2 bugs urgentes, 1 reunión improvisada)

“Mierda, olvidé el doc. Lo haré luego.”

2 semanas después.

Dev: (olvidó completamente)

3 meses después.

Nuevo dev: “¿Cómo funciona el SSO?”

Dev antiguo: “Eh… mira el código, el doc está obsoleto.”

El Problema:

Estadística Real:

En una encuesta a 200 desarrolladores:

5. Onboarding Pesadillesco (Nueva Persona Perdida)

El Escenario:

Nuevo desarrollador, Día 1.

Lead: “Lee estos 40 documentos de Notion para entender la arquitectura.”

Nuevo desarrollador pasa 3 días leyendo.

Día 4:

Nuevo dev: “Leí toda la doc. ¿Puedo empezar a codear?”

Lead: “Genial, ¿qué feature quieres atacar?”

Nuevo dev: “La API de pagos. El doc dice que usamos Stripe con webhooks.”

Lead: “Ah no, migramos a Adyen hace 2 meses. El doc está obsoleto.”

Nuevo dev: “…”

El Problema:

Resultado: Los nuevos desarrolladores abandonan rápidamente los docs y aprenden preguntando 100 preguntas a sus colegas.

Por Qué La Documentación Muere

Razón 1: Documentación Separada Del Trabajo

El Problema:

Los equipos usan:

Workflow típico:

  1. Desarrollador trabaja en una feature en Jira
  2. Código en GitHub
  3. Merge del PR
  4. ✅ ¡Feature terminada!
  5. … ¿Documentación? “Ah sí, debo actualizarla en Notion. Luego.”

Resultado: La documentación es una reflexión tardía (afterthought), desconectada del flujo natural de trabajo.

Nadie actualiza porque:

Razón 2: Sin Single Source Of Truth

El Problema:

Información dispersa entre:

Resultado: 6 fuentes de verdad = 0 fuente de verdad.

Nadie sabe dónde buscar. Nadie sabe qué info es correcta. Cada uno mantiene su propia versión mental de “cómo funciona realmente”.

Documentación dispersa entre 6 herramientas

Razón 3: Sin Dueño (Everybody’s Responsibility = Nobody’s Responsibility)

El Problema:

Lead: “¿Quién es responsable de mantener los docs actualizados?”

Respuesta A: “El equipo.”

Respuesta B: “El desarrollador que hace el cambio.”

Respuesta C: “El tech lead.”

Realidad: Nadie.

¿Por qué?

Porque “responsabilidad colectiva” = sin accountability individual.

Desarrollador: “Olvidé actualizar el doc, pero no es crítico.”

Tech Lead: “Pensé que el dev actualizaría el doc.”

Nuevo dev (6 meses después): “¿Por qué este doc está obsoleto?”

Todos: 🤷

El Enfoque Sinra: Documentación Viva Integrada Al Trabajo

Sinra elimina la documentación muerta al integrar contexto y trabajo en un sistema unificado.

El Concepto: Pages + Commentary = Documentación Viva

En Sinra, la documentación no vive en una herramienta separada. Vive con el trabajo.

Tres mecanismos:

  1. Pages: Documentación estructurada organizada por categorías
  2. Commentary: Contexto y decisiones capturados directamente en issues y capabilities
  3. Búsqueda unificada: Encuentra código, contexto y documentación en un lugar

Resultado: Imposible desincronizar (sin docs externos que mantener).

Anatomía De Una Feature Con Documentación Sinra

Retomemos el ejemplo de la autenticación.

Enfoque Tradicional (Notion + Código)

Paso 1: Escribir spec en Notion (“RFC-042: Arquitectura Auth”)

Paso 2: Codear en GitHub

Paso 3: Mergear el PR

Paso 4: “Actualizaré el doc de Notion luego” → nunca se hace

Resultado: Doc de Notion congelado, código evoluciona, desincronización total.

Enfoque tradicional vs Sinra

Enfoque Sinra (Documentación Integrada)

Paso 1: Crear capability “Autenticación SSO”

Descripción de la capability:

# Autenticación SSO

Permitir a los usuarios iniciar sesión vía Google y Microsoft OAuth2.

## Arquitectura
- Flujo OAuth2 (no JWT)
- Tokens en httpOnly cookies (no localStorage)
- Refresh tokens con rotación
- Duración de sesión: 12h

## Decisiones clave
[Ver commentary abajo]

Paso 2: Commentary de la capability (contexto capturado en tiempo real)

@lead: ¿Por qué OAuth2 y no JWT?

@architect: JWT requiere gestionar manualmente la revocación (complejo).
OAuth2 con refresh tokens ofrece revocación nativa vía el proveedor.

@dev1: ¿Y por qué httpOnly cookies en lugar de localStorage?

@architect: localStorage vulnerable a ataques XSS. httpOnly cookies
protegen mejor contra robo de tokens.

@lead: Aprobado. Adelante.

Decisión final: OAuth2 + refresh tokens + httpOnly cookies.
Razón: Seguridad y simplicidad de revocación.

Paso 3: Issues creadas bajo la capability

Paso 4: Desarrollo con commentary por issue

[Issue AUTH-120: Implement Google OAuth2 backend]

@dev1: Estoy usando la lib `passport-google-oauth20`. Config:
- Client ID/Secret almacenados en env vars
- Redirect URL: `/auth/google/callback`
- Scopes: profile, email

@architect: ✅ Perfecto. Asegúrate de validar el state param para CSRF.

@dev1: ✅ Hecho. Code review listo.

Paso 5: Código mergeado → Commentary preservado

6 meses después, nuevo desarrollador:

“¿Cómo funciona auth?”

Respuesta: Abre la capability “Autenticación SSO”

Ve:

Tiempo para entender: 15 minutos en lugar de 3 días.

Fiabilidad: 100% (porque contexto capturado en el momento del trabajo, no después).

Los Tres Pilares De La Documentación Viva Sinra

1. Pages: Documentación Estructurada Por Categorías

El Concepto:

Las pages de Sinra permiten crear documentación estructurada, organizada por categorías.

Casos de uso:

Diferencia con Notion:

Aspecto Notion/Confluence Sinra Pages
Enlace con trabajo ❌ Separado ✅ Integrado (puede enlazar issues, capabilities)
Búsqueda Siloed Unificada (encuentra pages + issues + commentary)
Actualización Manual (olvidada) Incentivada (en el mismo sistema)
Versionado Confuso Claro (vinculado a releases)

Ejemplo: Page “Authentication Setup”

# Authentication Setup

## Overview
Nuestro sistema usa OAuth2 con Google y Microsoft como proveedores.

## Quick Start
[Enlace a issues AUTH-120, AUTH-121]

## Architecture Decisions
[Enlace a commentary de la capability Autenticación SSO]

## Common Issues
[Enlace a bugs resueltos con tag #auth]

Beneficio: La page no está aislada. Apunta al contexto real (issues, commentary, bugs).

2. Commentary: Contexto Capturado En El Momento Del Trabajo

El Concepto:

El commentary (ya explicado en el post “Comunicación Dispersa”) captura:

Diferencia con documentación tradicional:

Doc tradicional (Notion):

“Usamos OAuth2.”

Commentary Sinra:

“Usamos OAuth2 en lugar de JWT porque [razones detalladas]. Discusión completa: [enlace]. Enfoques alternativos considerados: JWT (rechazado por revocación compleja), Session cookies (rechazado porque no es stateless).”

Resultado: El doc no es solo qué, sino por qué y cómo llegamos ahí.

3. Búsqueda Unificada: Encuentra Todo En Un Lugar

El Concepto:

Sinra ofrece búsqueda unificada que encuentra:

Escenario:

Desarrollador busca: “OAuth2 refresh tokens”

Resultados:

  1. Page: “Authentication Setup” → menciona refresh tokens
  2. Capability: “Autenticación SSO” → describe arquitectura de refresh tokens
  3. Issue: AUTH-123 “Implement refresh token rotation” → implementación detallada
  4. Commentary: Discusión sobre por qué rotación es obligatoria
  5. Bug: AUTH-247 “Refresh token expiry bug” → caso edge resuelto

Tiempo para encontrar info: < 1 minuto.

Con Notion + GitHub + Jira separados: 30 minutos (3 búsquedas en 3 herramientas).

Búsqueda siloed vs búsqueda unificada

Ejemplo Real: DataFlow (SaaS Analytics)

DataFlow (equipo de 15 personas, plataforma analytics)

Nota: DataFlow es una empresa real que hemos anonimizado bajo un nombre ficticio para proteger su confidencialidad.

Antes de Sinra: Documentación Muerta

Stack de docs:

Problemas Encontrados:

Incidente Revelador:

Nuevo desarrollador implementa feature “Exportar CSV” basándose en spec de Notion de hace 8 meses.

Spec decía: “CSV delimitado por coma, codificación UTF-8”

Código actual hacía: “CSV delimitado por tab, codificación UTF-16 (para soporte internacional de Excel)”

Resultado: Feature reimplementada incorrectamente. 1 semana perdida rehaciendo.

¿Por qué? Spec obsoleta, nunca actualizada después del cambio de implementación 6 meses antes.

Después de Sinra: Documentación Viva

Workflow:

  1. Cada feature documentada en descripción de capability + commentary
  2. Pages de Sinra para guías de setup y arquitectura
  3. Búsqueda unificada para encontrar contexto
  4. Cero docs externos (todo en Sinra)

Resultados (Después de 5 Meses):

Cita Lead Developer:

“Antes, decía a los nuevos ‘olvida los docs, lee el código’. Ahora digo ‘lee estas 5 capabilities y su commentary, entenderás todo’. Onboarding dividido por 3.”

Cita Product Manager:

“Se acabaron las 6 versiones contradictorias de una spec. Tenemos una capability con descripción + commentary. Es LA fuente de verdad. Si cambia, actualizamos la capability. Simple.”

DataFlow: Antes vs Después de Sinra

Notion + Confluence + GitHub Wiki vs. Sinra: Comparación

Aspecto Stack Multi-Docs Sinra Integrado
Ubicación doc 4-6 herramientas separadas 1 sistema unificado
Sincronización código ❌ Manual (olvidada) ✅ Integrada (en el trabajo)
Obsolescencia Frecuente (70%+) Rara (contexto vivo)
Versiones múltiples Sí (confusión) No (fuente única)
Búsqueda Siloed por herramienta Unificada (todo)
Onboarding 1-2 semanas 2-3 días
Actualización “Después” = nunca Capturada durante trabajo
Dueño Difuso (nadie) Claro (adjunto a capability)
Fiabilidad 30-40% 90%+

Las Cinco Señales De Que Tu Documentación Está Muerta

Señal 1: Dices “Olvida Los Docs, Lee El Código”

Si aconsejas sistemáticamente a los nuevos no leer la documentación, tus docs están muertos.

Señal 2: Nadie Sabe Qué Versión Es Correcta

Si tienes 5 documentos para la misma feature y nadie sabe cuál está actualizado, tus docs están muertos.

Señal 3: El Doc Dice Una Cosa, El Código Hace Otra

Si tu documentación contradice el código actual, tus docs están muertos (y son peligrosos).

Señal 4: Onboarding Toma 2+ Semanas

Si los nuevos pasan 2 semanas leyendo docs solo para reaprender todo leyendo código, tus docs están muertos.

Señal 5: “Actualizaré El Doc Después”

Si esta frase se dice después de cada feature, tu documentación está condenada a morir.

Cómo Usar Sinra Para Documentación Viva

Paso 1: Crear Pages Para Guías Estructuradas

Acción:

Resultado: Documentación estructurada accesible y vinculada al trabajo.

Paso 2: Capturar Contexto En Commentary

Acción:

Resultado: Contexto preservado en el momento del trabajo.

Paso 3: Usar Descripción De Capability Como Spec

Acción:

Resultado: Fuente única de verdad por feature.

Paso 4: Búsqueda Unificada Para Encontrar Info

Acción:

Resultado: Respuestas instantáneas, no 30 min de búsqueda.

Puntos de Acción: Resucita Tu Documentación

  1. Crea tus primeras pages de Sinra. Migra tus 5 guías más importantes de Notion.
  2. Captura contexto en commentary. Próxima decisión técnica → escribe en capability, no en Notion.
  3. Usa capabilities como specs. Descripción + Commentary = documentación viva.
  4. Abandona Notion para nuevas features. Todo nuevo trabajo documentado en Sinra.
  5. Onboarding con Sinra. Muestra 5 capabilities clave, no 40 docs de Notion.

El Punto Clave

La documentación muerta mata la productividad.

Entre specs obsoletas, versiones múltiples, docs contradictorios y onboarding pesadillesco, nadie confía en la documentación.

Sinra integra documentación y trabajo en un sistema unificado.

Las pages estructuran, el commentary captura el contexto, la búsqueda unifica todo.

El resultado:

Finalmente tienes documentación fiable.

Tu yo futuro te lo agradecerá.

¿Listo para resucitar tu documentación? Inicia una prueba gratuita de Sinra →

Descubre gestión de proyectos donde la documentación vive con el trabajo, no en un cementerio de Notion.