Módulo 3: Exportar, normalizar y estructurar el repositorio

6. Documentar un workflow para el handoff

Siguiente →

Descripción

Al terminar esta lección vas a poder documentar un workflow de n8n al nivel que exige un handoff profesional: un README por workflow con su propósito, su disparador, sus dependencias, las credenciales que requiere, las variables que usa y un diagrama de sus nodos. Vas a saber usar las sticky notes dentro del canvas —las notas que viajan en el propio JSON del workflow— para dejar explicaciones justo donde ocurren las cosas, y vas a tener claro el estándar concreto que persiguen las ofertas de trabajo cuando piden "documentación suficiente para que otro desarrollador lo tome".

Esto importa porque la documentación es lo que convierte tu trabajo en transferible, y transferible es lo que el mercado paga. Un workflow que solo tú entiendes es un riesgo para la empresa: si te vas, se va el conocimiento. Un workflow documentado es un activo: cualquiera del equipo puede tomarlo, entenderlo y mantenerlo. La frase "documented JSON" de las ofertas apunta exactamente a esto, y de las dos palabras, "documented" es la que más gente descuida —el JSON lo produce la exportación, pero la documentación la escribe una persona que decidió que valía la pena—.

Conexión con el módulo: la lección 5 armó el esqueleto del repo y reservó la carpeta docs/. Esta lección la llena. Es el segundo paso de "organizar": la 5 dijo dónde va cada cosa, esta dice qué hace cada cosa. Con la documentación en su lugar, el repositorio cumbre-automations cumple por fin la promesa completa —versionado, sin secretos, con diffs limpios, estructurado y documentado—, y queda listo para que la lección 7 automatice su mantenimiento y la 8 lo entregue. Después de esta lección, order-triage no es solo un archivo: es un archivo que otro puede retomar.

Documentar es responder las preguntas del que llega

Antes de escribir una línea de documentación, conviene entender qué es documentar bien, porque es fácil confundirlo con "escribir mucho". No lo es. Documentar bien es anticipar las preguntas que se va a hacer quien tome el workflow y responderlas antes de que las formule.

Imagina que un compañero nuevo hereda order-triage mañana, sin que tú estés disponible. ¿Qué se va a preguntar, en qué orden?

  1. ¿Para qué existe esto? Antes de mirar un solo nodo, necesita saber el propósito. Sin eso, todo lo demás es ruido sin marco.
  2. ¿Cómo se enciende? ¿Corre solo cada hora, o cuando llega un pedido, o cuando alguien aprieta un botón? El disparador define cuándo y por qué se ejecuta.
  3. ¿Qué necesita para funcionar? ¿De qué credenciales, servicios externos y variables depende? Sin esto, lo importa y no arranca.
  4. ¿Qué hace, en orden? El recorrido de los nodos: qué pasa primero, qué después, dónde se decide qué.
  5. ¿Qué puede salir mal? Los puntos frágiles, los supuestos, lo que hay que vigilar.

Documentar es responder estas cinco preguntas por escrito, de forma que quien llegue las encuentre resueltas. No en el orden en que se te ocurran, sino en el orden en que otro las necesita: primero el propósito, que da el marco; después el disparador y las dependencias, que sitúan el workflow en su entorno; luego el flujo; y al final los supuestos, que es el detalle fino que solo cobra sentido cuando ya entendiste el resto. Ese orden no es capricho: es el camino por el que una persona construye entendimiento, de lo general a lo particular. Fíjate que ninguna se responde mirando el JSON: el JSON dice cómo está construido el workflow, pero no para qué ni qué supone ni qué vigilar. Esa capa de "por qué" es la que solo una persona puede escribir, y es la que hace la diferencia entre un archivo y un entregable.

Piénsalo como la diferencia entre un aparato con manual y uno sin. Los dos funcionan igual. Pero el que tiene manual lo puede usar cualquiera; el que no, solo quien lo armó, y solo mientras se acuerde. La documentación es el manual de tu workflow.

Y hay una razón por la que esta documentación vive en el mismo repositorio que el workflow, y no en un documento suelto en algún drive: la documentación se versiona con la lógica. Cuando cambias order-triage y actualizas su README en el mismo commit, la historia de Git guarda las dos cosas juntas, sincronizadas para siempre. Quien mire una versión vieja del workflow ve la documentación de esa versión, no la de hoy. Un manual que vive fuera del repo se desincroniza el primer día; uno que vive dentro, viaja atado a la lógica que describe. Ese es todo el sentido de "documented JSON": no es JSON y aparte documentación, es un repositorio donde las dos son una sola cosa versionada.

El README por workflow

La forma concreta de esa documentación, en cumbre-automations, es un archivo Markdown por workflow dentro de docs/: docs/order-triage.md, docs/inventory-sync.md, y así. Cada uno responde las cinco preguntas con una estructura fija, para que todos se lean igual y quien conozca uno sepa navegar los demás.

Estas son las secciones de un README por workflow:

Propósito. Una o dos frases: qué problema de negocio resuelve. "Recibe los pedidos que entran por la tienda, los clasifica por prioridad con un modelo de IA y enriquece cada uno con los datos del cliente del CRM, para que el equipo de ventas atienda primero lo urgente." Nada de detalles técnicos aún; el qué y el para qué.

Disparador. Qué enciende el workflow. Un Webhook (llega una petición externa), un Schedule (cada X tiempo), un Manual Trigger (a mano). Incluye el detalle que otro necesita: si es Webhook, en qué ruta escucha; si es Schedule, con qué frecuencia.

Dependencias. De qué depende para funcionar: servicios externos (el CRM, el modelo de IA), otros workflows si los llama, nodos especiales. Es el mapa de "qué más tiene que estar vivo para que esto corra".

Credenciales requeridas. La lista de credenciales, con su tipo y su propósito —nunca sus valores, como martillamos en las lecciones 3 y 5—. "Header Auth Cumbre CRM key para leer el CRM; credencial de modelo de lenguaje Cumbre LLM key para el AI Agent." Esto le dice a quien importe el workflow exactamente qué credenciales crear en su instancia.

Variables. Los valores de configuración que el workflow usa y que pueden cambiar entre entornos: umbrales, URLs base, nombres de cola. Es la antesala del Módulo 4, que formaliza cómo esas variables difieren entre dev, staging y prod.

Diagrama de nodos. Una representación visual del flujo: qué nodo va a cuál. Lo vemos en detalle en un momento, porque hay una forma de hacerlo que se ve bien directamente en GitHub.

Notas y supuestos. La quinta pregunta —"¿qué puede salir mal?"—: los puntos frágiles, lo que se asume, lo que hay que vigilar. "Supone que el pedido siempre trae customer_id; si falta, el nodo del CRM falla." Esta sección es la que más agradece quien hereda el workflow, porque es el conocimiento que normalmente solo vive en la cabeza del autor.

El diagrama de nodos: Mermaid y el respaldo en ASCII

Un diagrama vale por mil palabras cuando se trata de entender un flujo. Hay dos formas prácticas de incluirlo en un Markdown, y conviene conocer las dos.

Mermaid es un lenguaje para describir diagramas con texto, que GitHub (y muchos visores de Markdown) renderiza como un dibujo automáticamente. La gracia es que el diagrama es texto —así que se versiona, se compara y se edita como cualquier otra parte del repo—, pero se ve como un diagrama cuando alguien abre el archivo en GitHub. Se escribe dentro de un bloque de código marcado como mermaid:

```mermaid
flowchart LR
    A[Webhook: nuevo pedido] --> B[AI Agent: clasifica]
    B --> C[HTTP Request: consulta CRM]
    C --> D[Set: arma respuesta]
```

Desármalo: flowchart LR dice "un diagrama de flujo de izquierda a derecha" (left to right); cada línea A[texto] --> B[texto] dibuja una caja con ese texto y una flecha hacia la siguiente. Las letras A, B, C son solo nombres internos para conectar las cajas. Cuando alguien abra docs/order-triage.md en GitHub, va a ver cuatro cajas conectadas por flechas, no el código.

El respaldo en ASCII. No todos los visores renderizan Mermaid, así que conviene tener una versión que se lea aunque no se renderice nada: un diagrama hecho con caracteres. Es más rústico pero funciona en cualquier lado:

Webhook ──► AI Agent ──► HTTP Request ──► Set
(nuevo     (clasifica)   (consulta CRM)   (arma
 pedido)                                   respuesta)

¿Cuál usar? Para un repo en GitHub, Mermaid se ve profesional y se mantiene fácil. Si no sabes dónde se va a leer la documentación, el ASCII es a prueba de balas. Muchos equipos ponen los dos: el Mermaid para quien lo ve renderizado, y una línea de ASCII como resumen rápido. No te obsesiones con esto; un diagrama simple y correcto vale más que uno elaborado y desactualizado.

Ejemplo trabajado: docs/order-triage.md

Juntemos todo en el README real de order-triage. Este es el archivo completo tal como viviría en docs/order-triage.md:

# order-triage

## Propósito
Recibe los pedidos que entran por la tienda en línea, los clasifica por
prioridad con un modelo de IA (urgente / normal / requiere revisión humana)
y enriquece cada uno con los datos del cliente traídos del CRM. El objetivo
es que el equipo de ventas atienda primero lo urgente sin revisar a mano.

## Disparador
- **Tipo:** Webhook (POST)
- **Ruta:** `/new-order`
- **Se enciende:** cada vez que la tienda dispara un pedido nuevo.

## Dependencias
- **CRM de Cumbre** (servicio externo, vía HTTP Request) — tiene que estar
  accesible para que el enriquecimiento funcione.
- **Modelo de lenguaje** (vía nodo AI Agent) — clasifica el pedido.

## Credenciales requeridas
| Credencial | Tipo | Para qué |
|---|---|---|
| Cumbre CRM key | Header Auth | Leer datos del cliente en el CRM |
| Cumbre LLM key | (modelo de lenguaje) | Clasificar el pedido con el AI Agent |

> Los valores reales NO están en este repo. Créalos en tu instancia; ver
> `credentials/README.md`.

## Variables
| Variable | Ejemplo | Para qué |
|---|---|---|
| `CRM_BASE_URL` | `https://crm.cumbre.example` | URL base del CRM (cambia por entorno) |
| `PRIORITY_THRESHOLD` | `2000` | Monto sobre el que un pedido se marca urgente |

## Diagrama de nodos
```mermaid
flowchart LR
    A[Webhook: nuevo pedido] --> B[AI Agent: clasifica prioridad]
    B --> C[HTTP Request: consulta CRM]
    C --> D[Set: arma respuesta enriquecida]
```

## Notas y supuestos
- Supone que cada pedido trae `customer_id`. Si falta, el nodo del CRM
  responde 404 y el workflow se detiene ahí. (Pendiente: manejar ese caso.)
- La clasificación del AI Agent es una sugerencia, no una decisión final:
  el equipo puede reasignar prioridad a mano.
- El CRM tiene límite de peticiones por minuto; con picos de pedidos muy
  altos, considerar un nodo de espera. Aún no es un problema en producción.

Mira lo que logra este documento. En una pantalla, alguien que nunca vio order-triage sabe para qué existe, cómo se enciende, de qué depende, qué credenciales crear, qué variables ajustar por entorno, cómo fluye, y —lo más valioso— qué supone y qué vigilar. Podría tomar el workflow mañana. Eso es un handoff.

Y fíjate en lo que no tiene: no explica qué es un Webhook ni cómo funciona un nodo HTTP Request. Eso lo sabe cualquier desarrollador de n8n; documentarlo sería ruido. La documentación buena asume el conocimiento general del oficio y se concentra en lo específico de este workflow. Documentar de más entierra lo importante bajo lo obvio.

Las sticky notes: documentación que viaja en el JSON

Hay una segunda capa de documentación, complementaria al README, que vive dentro del propio workflow: las sticky notes.

Una sticky note en n8n es un nodo especial que no hace nada en la ejecución —no procesa datos, no se conecta al flujo— y cuyo único trabajo es mostrar un texto pegado en el canvas, como un post-it sobre un tablero. Lo agregas desde el panel de nodos igual que cualquier otro, escribes texto (admite Markdown), y lo colocas junto al nodo o grupo de nodos que quieres explicar. Puedes cambiarle el color y el tamaño para agrupar visualmente.

Aquí está lo que las hace relevantes para este módulo: la sticky note es un nodo, y los nodos viajan en el JSON exportado. Cuando exportas order-triage, la nota se va con él, como un nodo de tipo n8n-nodes-base.stickyNote con tu texto adentro. Es decir, se versiona sola, sin que hagas nada extra, y viaja a cualquier instancia donde importes el workflow. Quien abra order-triage en el editor —no en el repo, en n8n mismo— ve tus explicaciones pegadas justo donde importan.

Esto resuelve un problema que el README no resuelve tan bien: la documentación de proximidad. El README es genial para la vista general, pero cuando alguien está mirando un nodo específico en el editor y se pregunta "¿por qué este nodo tiene esta configuración rara?", no va a ir al repo a buscar el README. Una sticky note al lado del nodo responde ahí mismo, en el momento exacto de la duda.

La regla de cuándo usar cuál:

  • README (en docs/): la vista general, el propósito, las dependencias, el diagrama. Lo que alguien lee antes de abrir el workflow.
  • Sticky note (en el canvas): la explicación puntual de un nodo o grupo raro. Lo que alguien necesita mientras mira el workflow.

Un buen ejemplo de sticky note en order-triage, pegada junto al nodo HTTP Request:

📌 Este nodo consulta el CRM con el customer_id del pedido.
Si el pedido no trae customer_id, el CRM responde 404 y el
workflow se detiene. Manejar ese caso está pendiente.
Credencial: Cumbre CRM key (Header Auth).

Fíjate que esta nota repite algo que también está en el README —el supuesto del customer_id—, y está bien que lo repita: el README lo dice para quien lee la vista general, la nota lo dice para quien está parado frente al nodo. La misma información en los dos lugares donde alguien podría necesitarla.

Un patrón que vale la pena adoptar es la nota de cabecera: una sticky note grande arriba a la izquierda del canvas, la primera que ve quien abre el workflow, con el propósito en una frase y un puntero al README completo. Algo como:

📋 order-triage — clasifica pedidos entrantes y los enriquece con datos del CRM.
Documentación completa: docs/order-triage.md en el repo.

Es el equivalente, dentro del editor, a la portada del repo: orienta en dos segundos y remite a la documentación detallada para quien quiera más. Con esa nota, alguien que abre el workflow en n8n sin haber visto el repo igual sabe qué está mirando y dónde leer más.

Una advertencia de seguridad, porque las sticky notes viajan en el JSON: nunca escribas un secreto en una sticky note. Como se exporta con el workflow, una llave de API escrita en una nota terminaría en el repo igual que si la hubieras puesto en un nodo. La nota documenta qué credencial se usa y de qué tipo, jamás su valor. La regla de la lección 3 no descansa.

Dos cosas que casi todos olvidan documentar

Hay dos piezas de documentación que la mayoría pasa por alto y que, en un workflow como order-triage, son de las más importantes. Vale la pena tratarlas aparte.

El contrato de entrada y salida

Un workflow con Webhook recibe datos de afuera. La pregunta que quien lo herede se va a hacer —y que ni el JSON ni el diagrama responden— es: ¿qué forma exacta tienen que tener esos datos? Si el pedido tiene que traer customer_id y line_items, y alguien manda uno sin customer_id, el workflow falla. Documentar el contrato de entrada es escribir un ejemplo del dato que el workflow espera:

## Contrato de entrada
El Webhook espera un POST con esta forma:

    {
      "order_id": "ORD-2041",
      "customer_id": "CUST-118",     // requerido; sin esto, el CRM falla
      "channel": "web",
      "line_items": [ ... ]
    }

Con eso, quien conecte una fuente nueva al Webhook sabe qué mandar sin adivinar ni leer el workflow nodo por nodo. Y de paso, documentas el supuesto crítico —customer_id es requerido— justo donde se entiende por qué. Lo mismo aplica a la salida: si el workflow devuelve un pedido enriquecido con un campo priority, muéstralo, para que quien consuma esa salida sepa qué esperar.

Lo específico de un workflow con IA

order-triage usa un nodo AI Agent, y los nodos de IA tienen documentación propia que un workflow común no necesita. Tres cosas que hay que dejar por escrito:

  • Qué modelo usa y por qué. "Clasifica con un modelo de lenguaje vía la credencial Cumbre LLM key." Si el modelo se puede cambiar por entorno —uno más barato en dev, uno mejor en prod—, dilo; es justo el tipo de cosa que el Módulo 4 y el Módulo 5 tratan.
  • Qué se le pide (la instrucción). El prompt o instrucción del sistema es lógica del workflow tanto como la configuración de cualquier nodo. Documenta qué le pides al modelo: "Clasifica el pedido en urgent, normal o needs_review según el monto y el historial del cliente." Sin esto, nadie entiende por qué el modelo decide lo que decide.
  • Que la salida no es determinista. Esta es la advertencia clave y la que más sorprende a quien viene de workflows normales: un modelo de IA puede dar respuestas distintas ante la misma entrada. Un nodo If siempre decide igual; un AI Agent, no necesariamente. Documentarlo evita que alguien reporte como "bug" algo que es la naturaleza del componente, y prepara el terreno para el Módulo 5, que enseña a probar workflows con IA a pesar de esa variabilidad.

Estas dos secciones —contrato de datos y notas de IA— son las que separan una documentación "correcta" de una que de verdad deja a otro tomar un workflow moderno con IA sin sufrir.

El estándar de las ofertas: "que otro lo pueda tomar"

Vale la pena poner nombre al estándar que perseguimos, porque no es "documentar mucho" ni "documentar bonito". Es un criterio concreto, y las ofertas de handoff lo expresan casi con estas palabras: documentación suficiente para que otro desarrollador tome el workflow y lo mantenga sin ayuda del autor.

"Suficiente" es la palabra clave, y corta en las dos direcciones:

  • Suficiente hacia arriba: tiene que alcanzar. Si un desarrollador competente abre tu repo y no puede arrancar el workflow, o no entiende para qué existe, o no sabe qué credenciales crear, la documentación no es suficiente, por más páginas que tenga.
  • Suficiente hacia abajo: no tiene que sobrar. Documentar cada nodo obvio, explicar qué es un Webhook, repetir lo que el JSON ya dice claramente —eso no es más documentación, es más ruido, y entierra lo que de verdad importa.

La prueba práctica, que puedes aplicar tú mismo, es la prueba del desconocido: dale tu repo a alguien que conozca n8n pero no conozca este workflow, y pídele que lo ponga a correr y te explique qué hace. Donde se atore, ahí falta documentación. Donde se aburra leyendo lo obvio, ahí sobra. El punto justo es donde esa persona avanza sola, sin atorarse y sin bostezar.

Ese estándar —"otro puede sin mí"— es el mismo que atraviesa todo el módulo, aplicado ahora a la documentación. Un repo que lo cumple es, literalmente, lo que las mejores ofertas piden por escrito. No es un extra: es el entregable.

Errores comunes

Documentar el cómo y olvidar el por qué (conceptual). Qué pasa: alguien escribe una documentación que describe nodo por nodo qué hace cada uno —"el nodo Set agrega un campo priority"— pero nunca dice para qué existe el workflow ni qué supone. Por qué pasa: el cómo se lee directo del canvas, así que es lo fácil de escribir; el por qué hay que pensarlo. Cómo detectarlo: si tu documentación se puede reconstruir mirando el workflow, no está agregando nada; el valor está en lo que el workflow no dice de sí mismo. Cómo corregirlo: concéntrate en propósito, supuestos y "qué vigilar" —las tres cosas que solo tú sabes y que el JSON no revela—. El cómo déjalo para el diagrama y las sticky notes puntuales.

Escribir un secreto en una sticky note o en el README (práctico y peligroso). Qué pasa: alguien, para que "quede documentado", pega la llave del CRM en una sticky note o en el README del workflow. Como la nota viaja en el JSON y el README está en el repo, el secreto termina versionado. Por qué pasa: en el momento se siente útil tener la llave "a mano" junto a la explicación. Cómo detectarlo: busca en tus notas y READMEs cualquier cosa con forma de llave (sk-..., Bearer ..., contraseñas). Cómo corregirlo: la documentación dice qué credencial se usa y de qué tipo, nunca su valor. Si encuentras un secreto documentado, además de borrarlo, rota la credencial (lección 3): estuvo en texto plano, así que hay que asumirlo comprometido.

Documentar una vez y no volver a tocarlo (conceptual). Qué pasa: alguien escribe una documentación excelente el día uno, cambia el workflow tres veces en los meses siguientes, y no actualiza el documento. Ahora la documentación miente: describe un workflow que ya no existe, y eso es peor que no tener documentación, porque induce a error. Por qué pasa: actualizar la doc es un paso extra fácil de saltar cuando hay prisa. Cómo detectarlo: cada vez que cambies un workflow, pregúntate si su README sigue siendo verdad; si no lo sabes, ábrelo y compara. Cómo corregirlo: trata la documentación como parte del cambio, no como un paso posterior —si cambiaste el disparador, actualiza la sección Disparador en el mismo commit—. La documentación desactualizada es deuda que cobra intereses.

Confundir cantidad con calidad (conceptual). Qué pasa: alguien escribe diez páginas de documentación creyendo que más es mejor, y entierra las tres cosas que importan bajo párrafos de relleno que explican lo obvio. Por qué pasa: "documentar bien" se confunde con "documentar mucho", y el volumen da una falsa sensación de rigor. Cómo detectarlo: aplica la prueba del desconocido; si esa persona se aburre o se pierde en el volumen, sobra texto. Cómo corregirlo: apunta a "suficiente", no a "exhaustivo". Una pantalla bien pensada vale más que diez páginas que nadie termina. La documentación es para leerse, y lo demasiado largo no se lee.

Ejercicios

Ejercicio 1 — Clasifica README o sticky note. Para cada pieza de documentación, di si va en el README por workflow (docs/) o en una sticky note en el canvas, y por qué: (a) el propósito general del workflow; (b) una advertencia sobre por qué un nodo HTTP Request específico tiene un reintento configurado; (c) el diagrama de todo el flujo; (d) la lista de credenciales requeridas; (e) una nota junto a un nodo Code que explica un cálculo poco obvio.

Ver solución

(a) README. Es vista general; se lee antes de abrir el workflow. (b) Sticky note. Es una explicación puntual de un nodo específico; se necesita mientras se mira ese nodo en el editor. (c) README. El diagrama del flujo completo es panorama, no proximidad. (d) README. La lista de dependencias es información de conjunto, y además conviene tenerla en el repo para quien no abre el editor. (e) Sticky note. Un cálculo poco obvio en un nodo Code se explica mejor pegado al nodo, donde surge la duda.

Por qué funciona: la regla es una sola —README para lo que se lee antes (panorama), sticky note para lo que se necesita mientras (proximidad)—. Si tienes clara esa distinción, sabes dónde poner cualquier pieza de documentación sin dudar. Y nota que algunas cosas, como el supuesto del customer_id, viven bien en los dos lados: no es error, es cubrir los dos momentos.

Ejercicio 2 — Escribe el diagrama Mermaid. El workflow inventory-sync tiene este flujo: un Schedule Trigger que corre cada hora, luego un HTTP Request que lee el stock de la tienda, luego un nodo Code que compara con el inventario interno, y finalmente un nodo que actualiza los que difieren. Escribe el bloque Mermaid de su diagrama de nodos.

Ver solución 
```mermaid
flowchart LR
    A[Schedule: cada hora] --> B[HTTP Request: lee stock de la tienda]
    B --> C[Code: compara con inventario interno]
    C --> D[Update: sincroniza los que difieren]
```

Las piezas: flowchart LR para un flujo de izquierda a derecha; cada nodo con una letra interna (A, B, C, D) y su texto entre corchetes; las flechas --> conectando en el orden del flujo. Si le pusiste flowchart TD (de arriba abajo, top-down) también es válido; es cuestión de qué se lee mejor. Lo que importa es que las cuatro cajas estén en el orden correcto y conectadas.

Por qué funciona: escribir un Mermaid a mano te muestra lo simple que es —texto plano que GitHub convierte en dibujo— y por qué es superior a pegar una captura de pantalla: el texto se versiona, se compara en un diff y se edita cuando el workflow cambia; una imagen no. Un diagrama que se mantiene solo con el resto del repo es un diagrama que no se desactualiza.

Ejercicio 3 — Aplica la prueba del desconocido. Toma un workflow tuyo (o order-triage con el README de esta lección) y hazte pasar por alguien que lo ve por primera vez. Sin abrir el editor, solo con el README: ¿podrías decir para qué existe, cómo se enciende, qué credenciales crear y qué vigilar? Anota cada pregunta que el README no te responda.

Ver solución

No hay una respuesta única; el resultado es tu lista de huecos. Lo que la mayoría descubre al hacerlo con honestidad es que su documentación responde bien el cómo pero se queda corta en dos lugares: los supuestos (qué asume el workflow sobre sus datos de entrada) y las variables por entorno (qué cambia entre dev y prod). Son justo las dos cosas que solo el autor sabe y que más frenan a quien hereda el trabajo.

Si tu README respondió las cuatro preguntas sin que tuvieras que abrir el editor, cumple el estándar de handoff. Si te atoraste en alguna, ahí está exactamente lo que falta escribir —ni más ni menos—.

Por qué funciona: la prueba del desconocido es la única forma honesta de medir si tu documentación es "suficiente", porque te obliga a leerla sin el conocimiento que tienes en la cabeza. Es incómoda a propósito: el objetivo es encontrar los huecos tú, antes de que los encuentre —con frustración— la persona que hereda el workflow.

Resumen y siguiente paso

En esta lección aprendiste que documentar es anticipar y responder las preguntas de quien hereda el workflow —para qué existe, cómo se enciende, qué necesita, qué hace y qué vigilar—, no escribir mucho. Armaste el README por workflow en docs/ con sus secciones fijas —propósito, disparador, dependencias, credenciales requeridas (sin valores), variables, diagrama de nodos y notas/supuestos—, y viste cómo hacer el diagrama con Mermaid, que GitHub renderiza a partir de texto versionable, con un respaldo en ASCII para donde no se renderice. Conociste las sticky notes, la documentación de proximidad que vive dentro del canvas y viaja en el JSON exportado —con la advertencia firme de que jamás lleva un secreto—. Y le pusiste nombre al estándar del módulo: "suficiente para que otro lo tome", medible con la prueba del desconocido, que corta el exceso tanto como la falta.

Antes de avanzar deberías poder: nombrar las secciones del README por workflow; explicar cuándo va un README y cuándo una sticky note; escribir un diagrama de flujo en Mermaid; documentar el contrato de entrada y las notas de IA de un workflow; y aplicar la prueba del desconocido a tu propia documentación.

Con esto, cumbre-automations ya es un repositorio completo: versionado, sin secretos, con diffs limpios, estructurado y documentado. Pero todo lo que hiciste hasta aquí lo hiciste a mano, comando por comando. La lección 7 lo automatiza: vas a escribir un script —un export.sh— que exporta con la CLI, normaliza el JSON y deja el repo listo para commit en un solo comando, para correrlo antes de cada commit y, si quieres, engancharlo como git hook. También vas a ver la alternativa Enterprise, el control de versiones con Git nativo de n8n, y el criterio honesto para decidir cuándo vale pagarla.

Recursos

← Anterior5. Estructurar el repositorioSiguiente →7. Automatizar la exportación con un script