Comunicación para Desarrolladores: Cómo Pensar, Reportar y Expresarte como Profesional

Un piloto que sabe volar pero no puede hablar con el control de tráfico aéreo es un riesgo, no un activo. Lo mismo aplica a los desarrolladores. La habilidad técnica te pone en la cabina. La comunicación te mantiene en el aire.

La mayoría de los desarrolladores aprenden a programar. Muy pocos aprenden a comunicar sobre código. La brecha aparece en todas partes: en mensajes de Slack que nadie lee, en actualizaciones de estado que confunden a los managers, en reportes de bugs que mandan a los compañeros en la dirección equivocada, en propuestas que mueren en una reunión porque nadie entendió qué se estaba proponiendo.

Este post trata esa brecha. No es una guía de estilo de documentación, ni reglas de gramática — eso importa, y otros posts lo cubren. Este post es sobre el pensamiento que precede a la escritura: cómo enmarcar un problema, quién es tu audiencia, qué necesitan de ti en este momento, y cómo dárselo en una forma sobre la que puedan actuar.

El Principio Central: La Comunicación Es un Servicio

Cuando escribes un mensaje, un reporte o un documento, estás prestando un servicio a un lector. Ese lector tiene un trabajo que hacer. Tu comunicación o le ayuda a hacerlo, o no.

Esto reformula la pregunta. En vez de “¿cómo explico lo que hice?”, pregunta “¿qué necesita saber esta persona ahora mismo para tomar una decisión o actuar?” La respuesta cambia según quién lee.

Un manager que pregunta “¿cómo va la función de autenticación?” necesita saber:

Si va a entregarse a tiempo
Si no, por qué y qué se está haciendo al respecto
Si necesita algo de su parte

No necesita saber qué librería JWT elegiste ni por qué refactorizaste el almacén de sesiones.

Un compañero que hace la misma pregunta necesita saber:

Qué está listo, qué está en progreso, qué está bloqueado
Con qué interfaces puede contar
Si algo podría afectar su trabajo

No necesita el marco de impacto de negocio.

La información es la misma. La forma es diferente. Conocer esa diferencia es toda la habilidad.

Mapa de Audiencias

Antes de escribir cualquier cosa — un mensaje, un reporte, un comentario — responde dos preguntas:

¿Quién lee esto?
¿Qué decisión o acción necesitan tomar después de leerlo?

Este es un mapa práctico de las personas con las que los desarrolladores se comunican más, y lo que cada una realmente necesita.

Tu Manager / Tech Lead

Lo que les importa: Progreso, riesgos y bloqueos. Traducen tu trabajo en algo que su manager pueda entender. Quieren saber si necesitas algo de ellos.

Lo que no les importa: Detalles de implementación, elecciones de librerías, debates internos que ya resolviste.

Su pregunta tácita cada vez que piden una actualización: “¿Estará esto listo cuando dije que estaría, y si no, qué tan grave es?”

Cómo se ve la buena comunicación:

“La autenticación va bien para el jueves. Login y registro funcionan de punta a punta. El restablecimiento de contraseña está en progreso — espero terminarlo mañana. Sin bloqueos, no necesito nada de tu parte.”

Cómo se ve la mala comunicación:

“He estado trabajando en la integración de bcrypt y refactoricé el middleware de sesiones. También investigué el enfoque JWT pero decidí usar sesiones por las implicaciones de CSRF. Todavía falta el restablecimiento de contraseña.”

La segunda versión entierra el mensaje principal (va bien para el jueves), obliga al manager a extraer el estado, y gasta espacio en decisiones que no le pidieron.

Tus Compañeros de Equipo

Lo que les importa: Claridad técnica. Quieren saber qué existe, cuál es la interfaz, qué estás asumiendo y qué podría romper su trabajo.

Lo que no les importa: Justificación de negocio, encuadre ejecutivo, ni nada que no tenga consecuencias para su código.

Su pregunta tácita: “¿Me afecta esto, y qué necesito saber para hacer mi trabajo?”

Cómo se ve la buena comunicación (en Slack o descripción de PR):

“Refactoricé el middleware de autenticación. Ahora acepta context.Context como primer argumento — fue necesario para soportar cancelación en el flujo de SSO. Si llamas a GetCurrentUser() en algún lugar, necesitarás actualizar la firma. Actualicé todos los puntos de llamada existentes en este PR, pero avísame si me perdí alguno.”

Cómo se ve la mala comunicación:

“Actualicé el middleware de auth para que sea más robusto y siga las mejores prácticas.”

La segunda versión no da a los compañeros información accionable. Tienen que abrir el PR, leer el diff y deducir las consecuencias por su cuenta. Eso es trabajo que les transferiste que podrías haber hecho tú.

Stakeholders No Técnicos (Producto, Diseño, Negocio)

Lo que les importa: Qué pueden y qué no pueden hacer los usuarios, y cuándo cambia eso. Riesgo e impacto al producto.

Lo que no les importa: Implementación técnica, arquitectura, detalles internos del sistema.

Su pregunta tácita: “¿Cómo afecta esto lo que prometimos a los usuarios?”

Cómo se ve la buena comunicación:

“La subida de archivos ya funciona. Los usuarios pueden adjuntar archivos de hasta 10MB en formato JPEG, PNG o PDF. Esperamos habilitarlo en producción el próximo miércoles. Un detalle: la primera subida desde una cuenta nueva será un poco más lenta (unos 3 segundos) mientras se aprovisiona la cuota de almacenamiento. Ese retraso desaparece en las subidas posteriores.”

Cómo se ve la mala comunicación:

“La integración de S3 está lista. Usamos URLs prefirmadas con carga multiparte. Se agregó middleware de escaneo de virus en el pipeline. Todavía hay que ajustar el timeout del Lambda.”

La segunda versión requeriría que un lector no técnico traduzca cada oración. No puede. Te hará preguntas que ya respondiste, o peor, adivinará.

Otros Desarrolladores (en PRs, revisiones de código, discusiones técnicas)

Lo que les importa: Corrección, claridad, trade-offs y si el código es mantenible por alguien que no es el autor.

Lo que no les importa: Defensividad, explicaciones vagas o muros de justificación.

Su pregunta tácita: “¿Este código es correcto, y puedo entenderlo lo suficientemente bien para mantenerlo después?”

Actualizaciones de Estado que Funcionan

La actualización de estado es la tarea de comunicación más común de un desarrollador, y la más comúnmente mal ejecutada. Esta es una estructura que funciona en cualquier formato — correo, Slack, standup, reporte escrito.

La Estructura de Cuatro Partes

1. Estado (qué es verdad ahora mismo) No lo que hiciste, no lo que planeas hacer. El estado actual de la cosa.

2. Progreso (desde la última actualización) Qué cambió desde la última vez. Esto es evidencia de que el trabajo avanza.

3. Siguiente (qué pasa después) La acción o hito inmediato siguiente. Un elemento. No un roadmap.

4. Bloqueos (qué necesitas, si hay algo) Solo si algo te está bloqueando genuinamente. Si nada te bloquea, omite esta sección completamente. Si lo incluyes, di qué necesitas y de quién.

Ejemplos

Standup diario (hablado):

“La integración de pagos está en revisión. Ayer terminé el manejo de webhooks y escribí pruebas para los casos de fallo. Hoy trabajo en el job de conciliación. Sin bloqueos.”

Treinta segundos. Completo. Accionable.

Actualización semanal escrita:

Feature de pagos — Semana 3

Estado: Integración completa, en pruebas QA.

Progreso esta semana: Manejo de webhooks, pruebas de casos de fallo, job de conciliación. Todas las pruebas pasando. QA inició el lunes.

Siguiente: Atender los hallazgos de QA esta semana, meta: despliegue en staging el viernes.

Bloqueos: Necesito aprobación del equipo de finanzas sobre la política de reembolsos antes de finalizar el flujo de reembolso. Esperando a María — baja urgencia, no bloquea el camino principal.

Reportes de Bugs: Dale a las Personas lo que Necesitan para Arreglarlo

Un mal reporte de bug es un problema dos veces: una cuando ocurrió el bug, y otra cuando cada desarrollador que lo mira tiene que hacer trabajo de investigación que debería haber hecho una vez quien lo reportó.

Un reporte de bug útil contiene exactamente lo necesario para reproducir, entender y verificar la corrección. Ni más, ni menos.

La Estructura del Reporte de Bug

Título: Describe el comportamiento, no tu interpretación. “El login falla después de restablecer contraseña” no “La autenticación está rota.”

Entorno: Dónde ocurrió. Sistema operativo, navegador, versión, ambiente (staging/producción), configuración relevante.

Pasos para reproducir: Ordenados, numerados, específicos. No “intenta iniciar sesión” — “ve a /login, ingresa el email X, ingresa la contraseña Y, haz clic en Enviar.”

Comportamiento esperado: Lo que debería haber ocurrido según el diseño o especificación.

Comportamiento actual: Lo que realmente ocurrió. Mensajes de error exactos, valores exactos, timestamps exactos.

Evidencia: Captura de pantalla, fragmento de log, request de red. Lo que prueba que el bug existe y ayuda a alguien a localizarlo en el sistema.

Impacto: Quién está afectado, con qué severidad, con qué frecuencia. Esto ayuda a priorizar.

Hipótesis (opcional): Si tienes una teoría sobre la causa, indícala claramente como hipótesis, no como hecho. “Sospecho que esto podría estar relacionado con el cambio de expiración de sesión en el PR #812, pero no lo he confirmado.”

Un Ejemplo Real

Malo:

Asunto: El login está roto

Hola, el login no funciona. Intenté iniciar sesión y solo muestra un error. ¿Alguien puede arreglarlo lo antes posible?

Bueno:

Bug: El login retorna 500 después de restablecer contraseña en producción

Entorno: Producción, Chrome 124, macOS 14.4. Reproducido también en Firefox. Staging no está afectado.

Pasos para reproducir:

Solicitar restablecimiento de contraseña para el usuario test@ejemplo.com

Hacer clic en el enlace de restablecimiento del correo

Ingresar una nueva contraseña y enviar

Intentar iniciar sesión con la nueva contraseña

Esperado: Login exitoso, redirección al dashboard.

Actual: HTTP 500 con mensaje “Error interno del servidor.” Sin más detalles mostrados al usuario.

Logs: ERROR auth.service: session.create: pq: duplicate key value violates unique constraint "sessions_pkey" a las 2025-06-15T14:32:01Z

Impacto: Afecta a todos los usuarios que restablecieron su contraseña después del 14 de junio (cuando corrió la migración del esquema de sesiones). Aproximadamente 12 usuarios afectados según los tickets de soporte hasta ahora.

Hipótesis: La migración del 14 de junio pudo haber dejado registros de sesión duplicados. La restricción única en el ID de sesión ahora se dispara en el login, lo que no ocurría antes.

La segunda versión le dice al ingeniero dónde buscar (la migración del esquema de sesiones), quién está afectado (restablecimientos posteriores al 14 de junio), y provee una hipótesis que podría ahorrar horas de investigación.

Descripciones de Pull Request que Obtienen Buenas Revisiones

La descripción de un pull request es el argumento del autor de por qué este código debería mergearse. Un revisor que tiene que inferir qué hace el PR, por qué existe y cómo probarlo tardará más en revisarlo, hará preguntas innecesarias o pasará por alto problemas reales.

La Estructura de la Descripción del PR

Qué hace este PR: Una oración. No un log de commits. El propósito legible por humanos.

Por qué: El problema que se resuelve o la función que se agrega. Enlaza el ticket, pero también explícalo en prosa. El revisor no debería tener que abrir Jira para entender el contexto.

Cómo: Una breve explicación del enfoque, especialmente para decisiones de diseño no obvias. Si elegiste el enfoque A sobre el B, di por qué. Si sabes que hay trade-offs, nómbralos.

Cómo probar: Instrucciones paso a paso que permiten al revisor ejecutar el comportamiento modificado por su cuenta. Un revisor que no puede reproducir el cambio no puede verificarlo.

Capturas de pantalla o grabaciones: Para cualquier cosa visual. Siempre.

Checklist: Pruebas escritas, documentación actualizada, migraciones ejecutadas, sin logs de debug.

Ejemplo

Malo:

Arreglé bug de auth

Bueno:

Fix: Prevenir sesión duplicada al restablecer contraseña

Qué: Limpia la sesión existente antes de crear una nueva durante el flujo de restablecimiento de contraseña.

Por qué: Después de la migración del esquema de sesiones del 14 de junio, los usuarios que restablecieron su contraseña recibían un error 500 en el login siguiente. La causa raíz era una violación de restricción única: el registro de sesión anterior no se eliminaba antes de insertar uno nuevo, resultando en dos registros con el mismo ID de sesión.

Cómo: Agregué una llamada DeleteSessionByUserID en auth.Service.ResetPassword() antes de crear la nueva sesión. Esto es seguro porque el enlace de restablecimiento en sí invalida la contraseña anterior, haciendo la sesión antigua inutilizable de todos modos.

Trade-off considerado: Podríamos manejar el conflicto con un upsert. Elegí eliminar-e-insertar porque es más claro sobre la intención (queremos invalidar la sesión anterior) y evita actualizar accidentalmente una sesión que debería desaparecer.

Cómo probar:

Restablecer contraseña para cualquier cuenta de prueba

Iniciar sesión con la nueva contraseña

Verificar: login exitoso, sin error 500

Verificar en BD: solo existe un registro de sesión para ese usuario

Checklist:

Prueba de regresión agregada (TestResetPassword_ClearsOldSession)

Probado en staging

Sin logs de debug

Comentarios de Code Review que Construyen, no Dañan

La revisión de código es colaboración, no juicio. El objetivo es mejor código y un equipo más fuerte — no demostrar que detectaste algo.

La forma en que redactas un comentario de revisión determina si resulta en mejora o en defensividad.

Los Tres Niveles de Comentarios de Revisión

Nivel 1 — Debe corregirse: Un problema real. Problema de corrección, fallo de seguridad, problema de rendimiento que importa.

Formato: Describe el problema, explica por qué importa, sugiere una corrección.

“Esta consulta no está parametrizada, lo que la hace vulnerable a inyección SQL. El valor email proporcionado por el usuario se interpola directamente en la cadena. Usa un prepared statement o el placeholder ? en su lugar.”

Nivel 2 — Debería considerarse: Un trade-off o un mejor enfoque, pero no un bloqueador.

Formato: Haz una pregunta o enmárcalo como sugerencia, no como exigencia.

“Me pregunto si cachear este resultado ayudaría aquí — el acceso a BD ocurre en cada request a /api/user, que se llama con frecuencia. Podría valer la pena medirlo. Feliz de mergear así y rastrear esto por separado si prefieres.”

Nivel 3 — Detalle menor: Estilo, nombres, claridad menor. No es un bloqueador. Márcalo explícitamente.

Formato: Etiquétalo “nit” para que el autor sepa que es baja prioridad.

“Nit: getUserFromCtx podría ser userFromContext para coincidir con el nombre en otros archivos de middleware. A tu criterio.”

Qué No Hacer

No dejes comentarios como estos:

“Esto está mal.” (¿Qué está mal? ¿Cómo debería corregirse?)
“¿Por qué lo hiciste así?” (Suena como acusación. Pregunta “¿consideraste X?” en su lugar.)
“Esto es ilegible.” (Reescríbelo y explica la mejora.)
“Hay una mejor manera.” (Entonces muéstrala.)

Un comentario sin camino a seguir es retroalimentación sin valor. Crea fricción y erosiona la confianza sin mejorar el código.

Proponer Cambios Técnicos a Gerencia No Técnica

Aquí es donde muchos desarrolladores fallan gravemente. Presentan una propuesta técnica a un manager y abren con el problema técnico. El manager no tiene suficiente contexto para evaluar el problema técnico. Se desconectan, aplazan o derivan a otra persona.

La solución es liderar con lenguaje de negocio y llegar al detalle técnico solo cuando el caso de negocio está establecido.

La Estructura de la Propuesta Técnica

El Problema (en términos de negocio): Comienza con lo que está fallando actualmente o qué oportunidad existe. Enmárcalo en términos que le importen al tomador de decisiones: experiencia del usuario, confiabilidad, costo, velocidad de entrega, riesgo.

El Impacto (ahora y proyectado): ¿Qué cuesta este problema hoy? ¿Qué cuesta en seis meses si no se hace nada? Hazlo concreto. No “el rendimiento empeorará” sino “nuestro p95 de tiempo de respuesta es de 1.8 segundos hoy; con el crecimiento actual proyectamos que alcanzará 4 segundos en Q4, momento en que la conversión históricamente cae un 12%.”

La Solución Propuesta (alto nivel): Lo que quieres hacer, en una o dos oraciones. No el diseño técnico — el resultado. “Queremos agregar una capa de caché que sirva las respuestas de API más comunes desde memoria en vez de consultar la base de datos cada vez.”

Qué Requiere: Tiempo, personas, costo. Sé honesto. Si son dos semanas de trabajo de ingeniería más $200/mes en infraestructura, dilo.

La Alternativa: Qué pasa si no hacemos esto. Los managers necesitan entender el costo de no actuar, no solo el costo de actuar.

La Solicitud: Termina con una petición específica. “Quisiera tu aprobación para comenzar esto en el próximo sprint” o “Necesito una decisión para el jueves para poder planificar el próximo ciclo.”

Ejemplo

Apertura mala:

“Necesitamos migrar de Redis a un caché distribuido porque nuestra instancia Redis de nodo único se está convirtiendo en un cuello de botella bajo el perfil de carga que estamos viendo, y la arquitectura actual no soporta escalado horizontal sin una refactorización mayor.”

Apertura buena:

“Tenemos un riesgo de confiabilidad del que quiero informarte. Aproximadamente el 30% de nuestro tráfico de API pasa por un solo servidor que no tiene respaldo. Si ese servidor cae — lo que ha pasado dos veces este año — toda la aplicación queda inaccesible hasta que lo reiniciemos. Quiero proponer un cambio que elimine ese riesgo y que también debería hacer la app un 40% más rápida para los usuarios.”

La segunda versión tiene la atención del manager. Ahora puedes explicar el detalle técnico — porque tienen una razón para importarles.

Postmortems: Escribir sin Culpar

Un postmortem no es un informe forense de quién cometió un error. Es un documento de aprendizaje que responde: qué ocurrió, por qué el sistema lo permitió, y qué estamos cambiando para que no pueda ocurrir de la misma manera otra vez.

El lenguaje de un postmortem es el lenguaje del comportamiento del sistema, no del fracaso personal. No “Juan subió una migración mala” sino “una migración corrió en producción sin una etapa de revisión.” No “el equipo no monitoreó el disco” sino “el sistema de alertas no tenía una regla para utilización de disco superior al 85%.”

Estructura del Postmortem

Resumen del incidente: Qué ocurrió, cuándo, cuánto duró, quién fue afectado. Máximo tres oraciones.

Línea de tiempo: Secuencia cronológica de eventos. Incluye cuándo comenzó el problema, cuándo fue detectado, qué acciones se tomaron y cuándo se resolvió. Usa timestamps UTC. Sé específico.

Causa raíz: La razón fundamental por la que ocurrió el incidente. Distingue entre el disparador inmediato (“un proceso consumió toda la memoria disponible”) y la causa raíz (“el límite de memoria no estaba configurado para este servicio, y no había monitoreo para detectar el crecimiento antes de que se volviera crítico”).

Factores contribuyentes: Otras condiciones que hicieron posible el incidente o lo empeoraron. Casi siempre hay múltiples.

Impacto: Usuarios afectados, ingresos afectados, violaciones de SLA, problemas de integridad de datos si los hubiera.

Qué salió bien: Cosas genuinamente buenas que limitaron el daño. Detección que funcionó, escalamiento que fue rápido, un runbook que realmente fue útil.

Qué salió mal: Brechas sistémicas, no fallos personales.

Elementos de acción: Específicos, con dueño, con fecha límite. No “mejorar el monitoreo” — “Agregar alerta de utilización de disco al 80% en Datadog — responsable: Ana — fecha: 20 de junio.” Cada elemento debe ser un cambio al sistema, proceso o herramientas.

Lenguaje que Ayuda

Usa voz pasiva deliberadamente para describir estados del sistema sin asignar culpa:

“La alerta no se disparó” en lugar de “nadie configuró la alerta”
“El procedimiento de rollback no estaba documentado” en lugar de “Carlos olvidó documentarlo”

Usa “nosotros” para describir acciones del equipo:

“No teníamos un entorno de staging que coincidiera con producción” en lugar de “el equipo falló en configurar staging correctamente”

Esto no es deshonestidad ni evasión. Es preciso. El problema casi nunca es una sola persona — es un sistema que permitió que el problema ocurriera. Arregla el sistema.

Mensajes de Slack y Asíncronos que Obtienen Respuestas

La mayoría de los mensajes de Slack de desarrolladores fallan porque optimizan para la conveniencia del emisor, no para la capacidad del receptor de responder. Enviar “oye, ¿tienes un minuto?” hace que el receptor haga todo el trabajo de averiguar qué necesitas, evaluar si puede ayudar y decidir cuándo responder. Eso es trabajo que le transferiste a alguien más.

Principios para Mensajes Asíncronos

Empieza con la pregunta real. No “oye” o “pregunta rápida” — la pregunta misma. El destinatario puede evaluar si puede ayudar sin un intercambio separado.

Da suficiente contexto para una respuesta completa. Si la persona necesita hacerte tres preguntas de seguimiento antes de poder responder, escribiste un mensaje incompleto.

Indica la urgencia con honestidad. “Esto me está bloqueando” significa algo diferente a “curioso cuando tengas tiempo.” Di cuál es. No digas que todo es urgente — la gente lo ignora.

Un tema por hilo de mensaje. Un mensaje con tres preguntas no relacionadas es un mensaje que se responde parcialmente y luego se olvida.

Ejemplos

Malo:

“oye tienes un segundo”

Bueno:

“Pregunta rápida sobre el webhook de pagos: ¿deberíamos reintentar en un 422 de Stripe, o tratarlo como un fallo permanente? Estoy a punto de implementar la lógica de reintento y quiero hacerlo bien. Sin prisa — antes del final del día está bien.”

Malo:

“El build está roto y también tenía una pregunta sobre la migración de base de datos que estamos haciendo y también quería ver si viste el Slack de producto sobre el plazo”

Bueno:

Tres mensajes separados (o un mensaje que lista explícitamente tres elementos numerados, facilitando responder a cada uno).

El Patrón “No Hello”

No envíes “hola” y esperes una respuesta antes de hacer tu pregunta. En comunicación asíncrona, esto duplica el tiempo para obtener una respuesta. Envía el mensaje completo de inmediato. La persona responderá cuando pueda, con todo lo necesario para darte una respuesta útil.

Propuestas Técnicas por Escrito

Cuando necesitas una decisión sobre un enfoque técnico — qué base de datos usar, si introducir una nueva dependencia, cómo manejar una preocupación transversal — una propuesta escrita supera a una reunión. Fuerza la claridad, crea un registro y permite a los revisores pensar antes de responder.

El Patrón RFC (Request for Comments)

Las grandes organizaciones de ingeniería (Google, Rust, Python, React) usan RFCs para decisiones importantes. Una versión simplificada funciona para equipos de cualquier tamaño.

Título: La decisión que se toma. No “¿Deberíamos usar GraphQL?” sino “Capa de API: REST vs GraphQL para la API orientada al cliente.”

Contexto y problema: Qué situación ha creado la necesidad de esta decisión. Sé factual y breve.

Solución propuesta: Tu recomendación, con suficiente detalle para evaluarla. Qué cambiará, qué será diferente, qué no cambiará.

Alternativas consideradas: Las opciones que evaluaste y por qué las descartaste. Esta es la parte más importante. Muestra tu pensamiento, previene que se vuelvan a discutir preguntas ya decididas y genera confianza en que la recomendación no es arbitraria.

Trade-offs: Lo que estás sacrificando con la solución propuesta. Ninguna opción es perfecta. Reconocer trade-offs es señal de pensamiento claro, no debilidad.

Preguntas abiertas: Cualquier cosa sobre la que tengas incertidumbre y necesites aportaciones.

Decisión y justificación (se completa después de la revisión): Una vez tomada la decisión, regístrala aquí con el razonamiento. Esto se convierte en la memoria institucional.

Ejemplo de Estructura

Título: Autenticación: Sesiones vs JWT para la API

Contexto: Estamos construyendo una nueva API que será consumida tanto
por nuestra app web como por una futura app móvil. Necesitamos decidir
sobre el mecanismo de autenticación antes de comenzar la implementación.

Solución propuesta: Autenticación basada en sesiones usando cookies
HTTP-only firmadas.

Justificación:
- Nuestra app web actual ya usa sesiones; la consistencia reduce
  la complejidad
- Las cookies HTTP-only previenen el robo de tokens por XSS
- La invalidación de sesiones es inmediata; la invalidación de JWT
  requiere infraestructura adicional (listas de revocación)
- Las apps móviles pueden usar auth basada en cookies; esto no
  es solo para web

Alternativas consideradas:
- JWTs: descartado porque la invalidación de tokens requiere una
  lista negra, lo que agrega la complejidad que estamos tratando
  de evitar, y el auth sin estado no es un requisito para este sistema
- OAuth con proveedor externo: fuera de alcance; esto es para
  consumidores internos de la API, no desarrolladores de terceros

Trade-offs:
- Las sesiones requieren almacenamiento del lado del servidor;
  usaremos Redis para esto
- El escalado horizontal requiere replicación de sesiones o
  sticky sessions; planeamos usar Redis, que maneja esto

Preguntas abiertas:
- TTL de sesión: ¿7 días con ventana deslizante, o fijo? Necesita
  aportación de producto.
- ¿Deberían las apps móviles compartir el almacén de sesiones
  con la app web?

Decisión: [se completará después de la revisión]

La Mentalidad Detrás de la Buena Comunicación Técnica

La buena comunicación técnica no es un estilo de escritura. Es una manera de pensar en el tiempo, el contexto y las necesidades de otras personas.

Piensa en lo que el lector ya sabe. No sobre-expliques a un experto ni sub-expliques a un principiante. Calibra.

Piensa en lo que el lector hará con esta información. Escribe para que pueda hacerlo. Elimina todo lo que no le ayude a hacerlo.

Piensa en qué pregunta estás respondiendo. Los mejores documentos son respuestas a preguntas específicas. “¿Cómo configuro el entorno de desarrollo?” es mejor que “Documentación del entorno de desarrollo.”

Piensa en qué pasa después de que lo leen. ¿Podrán tomar la acción que necesitas? ¿Tendrán la información para tomar una decisión? Si no, reescribe.

Piensa en el costo de la comunicación poco clara. Una actualización de estado vaga lleva a una reunión de seguimiento. Un mal reporte de bug lleva a un desarrollador a pasar medio día investigando lo incorrecto. Una descripción de PR sin contexto lleva a una revisión retrasada. El costo de la escritura poco clara siempre se paga — ya sea por el escritor que la reescribe, o por el lector que compensa con esfuerzo extra y preguntas.

Lo que Separa a los Desarrolladores Senior Comunicativamente

La brecha técnica entre un desarrollador junior y uno senior se cierra con años de práctica. La brecha de comunicación a menudo no se cierra porque nadie la enseña explícitamente.

Un desarrollador senior:

Ajusta vocabulario y profundidad para la audiencia automáticamente, sin que se lo pidan
Escribe actualizaciones antes de que se soliciten porque entiende la necesidad del manager de predecibilidad
Enmarca los problemas en términos de impacto y riesgo, no solo descripción técnica
Reconoce trade-offs en lugar de defender una sola posición
Escribe descripciones de PR que hacen a los revisores más rápidos, no más lentos
Entrega malas noticias pronto, con contexto y un plan, en lugar de tarde, como sorpresa
Solicita retroalimentación sobre propuestas en lugar de anunciar decisiones
Escribe postmortems sin protegerse ni culpar a otros

Nada de esto requiere habilidades de escritura excepcionales. Requiere el hábito de pensar en la comunicación como una responsabilidad profesional, no como algo secundario.

El desarrollador que entrega código excelente y lo explica mal siempre será superado por el desarrollador que entrega buen código y se comunica excelentemente. La comunicación multiplica el impacto. Es cómo tu trabajo se vuelve visible, cómo tu juicio gana confianza, y cómo tu influencia se extiende más allá del código que personalmente escribiste.

Escribir es el pensamiento hecho visible. Cuando tu escritura es clara, precisa y considerada con el lector, le dice a todos a tu alrededor que tu pensamiento es igual. Esa reputación, una vez establecida, abre puertas que la habilidad técnica por sí sola no puede.