Documentar para la fricción: tips para evitar documentación muerta, malentendidos y falsas certezas.

La documentación no solo sirve para informar, también puede usarse para generar fricción útil. “Documentar para la fricción” implica escribir lo justo y necesario para que otros cuestionen, corrijan o propongan mejoras. En vez de intentar cubrir todos los casos posibles, se documentan los supuestos, los límites y las razones detrás de las decisiones. Esto fuerza la colaboración activa y evita la documentación muerta que nadie lee ni discute.

En fintech.works, como software factory, nos tomamos muy en serio la documentación, ya que en el área financiera es prácticamente imposible avanzar proyectos sin documentación clara que ilumine el camino y nos ayude a sortear temas como:

1. Estándares internacionales ISO.
2. Reglas de integración a marcas como Visa y Mastercard.
3. Implementaciones de Google Pay y Apple Pay.
4. Facilitar que nuestros clientes entiendan cómo funcionan nuestros productos.

Como en toda software factory, nuestras herramientas de preferencia para documentación siempre fueron los clásicos documentos de arquitectura, pull-requests bien redactados, tickets con mucho contexto/comentarios y Swagger UI/Stoplight en todas nuestras APIs.

Estas herramientas se mantienen, pero con el tiempo fuimos incluyendo algunas técnicas para aumentar la "fricción" en ellas que mejoraron nuestra manera de documentar tanto para el desarrollo interno como para la comunicación con los clientes.

En este blog queremos compartir estos cambios que consideramos tuvieron el mayor impacto en nuestra documentación y podrían ser de utilidad para los que lean el blog.

Conociendo la documentación ideal

Como software factory manejamos una gran cantidad de tipos de documentaciones técnicas, desde manuales de instalación hasta comentarios en pull-requests cada uno con su propio formato y contenido, esto hace que parezca imposible poder definir (en un blog) un formato ideal para cada uno de ellos.

Pero en nuestra larga experiencia escribiendo y utilizando documentación técnica logramos armar un framework que nos permite escribir documentos que cumplan 2 objetivos y nada más:

1. Ser de utilidad para el que lee los documentos (clientes o fintech.works en el futuro)
2. Ser de utilidad para el que escribe los documentos (fintech.works)

Tener solo estos 2 objetivos puede parecer algo lógico y demasiado simple, sin embargo, en nuestra experiencia es todo un arte poder escribir documentación que logre estos 2 objetivos sin un proceso estricto de redacción disciplinada y varias rondas de revisión por parte de compañeros y clientes.

Cada vez que empezamos un documento técnico debemos tener estos 2 objetivos en mente, ya que sin importar el formato o el tipo de documento que estamos escribiendo, aplicar los principios de cada objetivo harán que la redacción sea más rápida, útil para todos los involucrados y mucho más sencilla de mantener y entender a largo plazo.

Objetivo 1: Ser de utilidad para el que lee

El que "lee" un documento técnico puede ser un posible cliente, un nuevo integrante del equipo o incluso nosotros mismos en unos años, de cualquier manera el objetivo principal se puede dividir en 3:

1.1 Ser fácil de comprender y no solo de leer

Un documento útil no es aquel que se puede leer de principio a fin, sino aquel que se puede entender rápido. La información debe estar organizada de forma que una persona con el contexto adecuado pueda encontrar lo que necesita sin esfuerzo. Esto implica usar ejemplos reales, diagramas con propósito, y lenguaje concreto (no burocrático).

1.2 Ser evaluable

Cada documento debería poder responder a la pregunta: ¿cómo sé si esto sigue siendo cierto hoy?

La documentación que no puede ser evaluada termina convirtiéndose en ruido. Incluir métricas, condiciones de validez o referencias a decisiones (por ejemplo, un ADR) permite que otros juzguen si sigue siendo relevante o necesita actualizarse.

1.3 Ser accionable

El lector debe poder hacer algo con lo que lee: tomar una decisión, aplicar una configuración, detectar un riesgo o iniciar una conversación. Un documento técnico que no impulsa ninguna acción concreta es sólo un archivo más.

Objetivo 2: Ser de utilidad para el que escribe

La documentación también tiene que servirle a quien la escribe. No como un trámite o una tarea de cierre, sino como una herramienta de pensamiento. Escribir documentación obliga a explicitar supuestos, decisiones y dependencias que muchas veces se dan por obvias durante el desarrollo. Cuando el autor se ve forzado a justificar lo que hace, surgen las inconsistencias, los huecos lógicos y las áreas grises del sistema. Este también lo dividimos en 3:

2.1 Ser fácil de actualizar

Una documentación útil no es la que cubre todo, sino la que puede sobrevivir al cambio. Si mantener actualizada esta documentación es un dolor, morirá pronto.

Por eso, cada documento debe tener una relación clara con su fuente de verdad: si algo cambia en el código, los pipelines o las APIs, debe ser evidente dónde actualizar la documentación.

2.2 Ser fuente de claridad para el pensamiento

Escribir es una forma de diseñar. Al documentar, el autor se ve obligado a explicitar su razonamiento, lo que suele exponer supuestos, contradicciones o dependencias que no eran evidentes.

En fintech.works, muchas discusiones técnicas se resolvieron durante la redacción de los documentos (no después), porque el proceso de escribir revelaba los puntos débiles de las ideas.

Un buen documento no solo comunica una solución, también demuestra que fue pensada.

2.3 Ser fuente de trazabilidad de decisiones

Registrar las razones detrás de una decisión es tan importante como describir la decisión en sí. Los ADRs (Architecture Decision Records) nos ayudaron a dejar constancia de por qué algo se hizo de cierta manera, y bajo qué contexto.

Esto evita que los equipos futuros pierdan tiempo rediscutiendo lo que ya se había resuelto y permite auditar decisiones clave sin depender de la memoria colectiva.

En términos prácticos: documentar no solo lo que hay, sino por qué está así.

Qué es "Documentar para la fricción"

Ahora que sabemos qué objetivos debe cumplir nuestra documentación podemos ver los mecanismos reales que utilizaremos para tratar de lograrlos.

Al comienzo del blog anotamos la definición de documentación para la fricción, en resumen los objetivos de escribir documentos que creen fricción son:

1. Generar cuestionamientos sobre decisiones
2. Generar correcciones en base a los cuestionamientos
3. Proponer mejoras al producto
4. Documentar supuestos y expectativas del producto
5. Documentar límites del producto

Estos objetivos de "creación de fricción" se alinean perfectamente con nuestros 2 objetivos principales, de tal forma que al aplicarlos tal y como explicaremos en las siguientes secciones, logramos que el documento que está siendo escrito pueda ser útil tanto para el que lo redacta como para el que lo escribe.

El origen de la fricción: ADRs

Hace un par de años empezamos a utilizar los Architecture Decision Records (ADRs) en fintech.works, estos se utilizan de manera convencional guardando todos los registros en un repositorio central desde el cual podemos hacerlos referencia mediante links en cualquier otra documentación. A medida que los fuimos utilizando cada vez más, notamos que las interacciones entre los compañeros como comentarios de cada ADR ayudaba a entender más la decisión que el propio ADR. A partir de esto tratamos de expandir esta dinámica de fricción a otros documentos, con lo cual nació "Documentar para la fricción".

Como convertir todos nuestros documentos de arquitectura, manuales y diagramas a un formato ADR es imposible, nos limitamos a tratar de lograr esta fricción mediante cambios más sutiles, aunque el formato ADR en sí también puede utilizarse directamente en tickets en incluso publicaciones de blog como la de Michael Nygard sobre ADRs.

Creando fricción en documentos de arquitectura

Los documentos de arquitectura suelen ser los más “respetados” y al mismo tiempo los más ignorados. Suelen convertirse en PDFs estáticos que envejecen mal y ya no reflejan la realidad. Para que realmente cumplan su propósito, deben ser instrumentos de conversación, no piezas decorativas.

Mejoras aplicadas

1. Incluir preguntas, no solo respuestas.Cada decisión importante debe ir acompañada de una sección “Preguntas abiertas” o “Riesgos no resueltos”.Esto genera fricción porque invita a otros a cuestionar las suposiciones en lugar de asumir que todo está cerrado.
2. Conectar cada decisión con su contexto.Agregar enlaces o referencias cruzadas a los ADRs correspondientes, para que cualquier lector pueda entender por qué se eligió una tecnología o topología determinada.Esto fortalece la trazabilidad (objetivo 2.3) y permite evaluar vigencia (objetivo 1.2).
3. Usar diagramas con propósito.Cada diagrama debe responder a una pregunta específica, no ser una foto general del sistema.Ejemplo: un diagrama “de superficie de ataque” o “de flujo de auditoría” es mucho más útil que un diagrama general de componentes.
4. Incluir límites y no certezas.En lugar de decir “el sistema soporta 10.000 transacciones por segundo”, especificar “el sistema fue validado con 10.000 TPS bajo X condiciones de red y configuración de infraestructura”.Esto genera fricción saludable: quien lea sabrá qué probar si cambia algo y qué se puede esperar del sistema bajo condiciones diferentes.

Creando fricción en diagramas de arquitectura

Los diagramas muchas veces se crean como entregables finales, pero rara vez se usan para tomar decisiones.

Cuando se documenta para la fricción, los diagramas deben ser una herramienta de validación compartida, no un artefacto bonito.

Mejoras aplicadas

1. Adoptar un estándar visual compartido, pero flexible.En fintech.works combinamos el modelo C4 con diagramas tipo Excalidraw de acuerdo a la audiencia y el nivel de detalle.La fricción surge cuando dos audiencias distintas ven el mismo sistema con distintas capas de detalle, y deben reconciliar sus visiones.
2. Agregar anotaciones y “zonas de duda”.No todo debe estar perfectamente definido. Señalar zonas grises (por ejemplo: “esta integración aún no tiene SLA acordado”) estimula conversaciones útiles.
3. Evitar el “diagrama único”.En vez de un monolito visual, usar varios diagramas pequeños, cada uno respondiendo una pregunta concreta: seguridad, resiliencia, comunicación, estados transaccionales, etc.Cada diagrama que fuerza una pregunta diferente es una oportunidad de mejora.

Ejemplo de diagrama monolítico general:

Ejemplo de diagrama que responde a la pregunta "Cuál es el flujo de validación de una transacción?":

Creando fricción en manuales de instalación y uso

Los manuales suelen ser los más propensos a quedar obsoletos y a perder valor. Sin embargo, con pequeñas modificaciones pueden transformarse en documentos que generan aprendizaje y colaboración.

Mejoras aplicadas

1. Versionar el manual junto al código.Si el manual vive en el mismo repositorio que el código, cada pull request puede exigir una actualización o confirmación del texto asociado.Esto reduce el costo de mantenerlo vivo (objetivo 2.1).
2. Incluir una sección “Errores esperables”.En lugar de ocultar las limitaciones, listarlas. Por ejemplo:“Durante la instalación, si el API Gateway devuelve 403, probablemente el rol IAM no tenga permiso para X”.Esto crea fricción útil: el lector aprende y el autor documenta conocimiento tácito.
3. Agregar “motivos de diseño” en pasos críticos.En vez de solo decir “Ejecutar el script init-db.sh”, incluir una breve nota del porqué:“Separamos la creación del esquema por seguridad en despliegues multi-tenant”.Esto ayuda a la claridad (2.2) y al aprendizaje del lector (1.1).
4. Simplificar el formato y enlazar pruebas vivas.Los ejemplos de configuración o despliegue deben referenciar archivos reales del repositorio o pipelines, no copias estáticas.Esto permite evaluar si el manual sigue siendo cierto (1.2).

Ejemplo de tabla con errores comunes para troubleshooting:

Creando fricción en documentaciones de APIs

Las APIs son el punto más sensible entre equipos y sistemas externos. Documentarlas para la fricción es esencial, ya que los errores de interpretación se traducen directamente en errores de integración.

Mejoras aplicadas

1. Incluir ejemplos de uso “válido” y “no válido”.Mostrar no solo cómo se usa correctamente la API, sino también casos que deberían fallar.Esto ayuda a definir el contrato y fomenta discusiones sobre límites y validaciones.
2. Combinar documentación técnica y narrativa.El swagger o OpenAPI describe el qué, pero agregar pequeñas notas sobre el por qué (por ejemplo, en Stoplight o Postman) aporta contexto.“El campo authorization_id se mantiene opcional por compatibilidad con versiones previas”.
3. Conectar la documentación con pruebas automáticas.Cada ejemplo del swagger debería tener un test asociado (por ejemplo, mediante contract testing o Postman tests).Esto garantiza que lo que está documentado sea cierto hoy (1.2).
4. Visibilizar dependencias externas.Especificar qué servicios externos influyen en la API (bancos, gateways, colas).Esa visibilidad genera fricción útil cuando alguien planifica cambios y detecta impactos no evidentes.

Ejemplo de especificación API con comentarios que:

1. Generan conversaciones
2. Exponen riesgos
3. Respaldan decisiones

paths:
  /payments:
    get:
      summary: Listar pagos registrados
      description: Devuelve una lista de pagos filtrable por fecha, estado o comercio.
      tags:
        - Payments
      # ¿Hay alguna razón para no paginar esta respuesta? Podría crecer mucho con el tiempo.
      # GENERA CONVERSACIONES
      operationId: listPayments
      parameters:
        - name: merchantId
          in: query
          required: false
          description: ID del comercio a filtrar.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filtra los pagos por estado.
          schema:
            type: string
            enum: [PENDING, COMPLETED, FAILED]
      responses:
        '200':
          description: Lista de pagos obtenida correctamente.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Payment'
        '400':
          description: Parámetros inválidos.
        '500':
          description: Error interno del servidor.
      # No hay rate limiting documentado, esto puede generar sobrecarga en el backend.
      # EXPONE RIESGOS

    post:
      summary: Registrar un nuevo pago
      description: Crea una solicitud de pago y la envía para procesamiento.
      tags:
        - Payments
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPaymentRequest'
      responses:
        '201':
          description: Pago creado exitosamente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Datos del pago inválidos.
        '422':
          description: Error de validación o negocio.
        '500':
          description: Error interno del servidor.

components:
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        merchantId:
          type: string
        amount:
          type: number
          format: float
          description: Monto total de la transacción.
          # El uso de ISO 4217 en montos se documenta en ADR-018 (Internationalization rules).
          # HACE REFERENCIA A DECISIONES
        currency:
          type: string
          description: Código de moneda ISO 4217, por ejemplo 'USD' o 'PYG'.
        status:
          type: string
          enum: [PENDING, COMPLETED, FAILED]
        createdAt:
          type: string
          format: date-time

Conclusión

Documentar para la fricción no se trata de poner trabas, sino de crear un espacio de diálogo real. Cuando la documentación está pensada para generar preguntas, aclarar supuestos y abrir discusiones, deja de ser un trámite y se convierte en una herramienta viva que mejora el producto y el trabajo en equipo. En fintech.works entendimos que los mejores documentos no son los que tienen todas las respuestas, sino los que invitan a conversar y seguir construyendo mejores soluciones juntos.

Fuentes

Architecture Decision Records (ADRs) — propuesta original de Michael Nygard (Documenting Architecture Decisions)

Just Enough Documentation de Simon Brown — aboga por documentar decisiones y contextos, no detalles exhaustivos

Runbooks as Conversations (Google SRE Book, capítulo 28) — plantea que un buen runbook debe enseñar, no solo instruir

Working with Legacy Code (Michael Feathers) — sugiere documentar límites y riesgos, no comportamientos ideales

Docs-as-Code movimiento — GitLab, Spotify y HashiCorp usan PRs de documentación como espacios de revisión activa