La regla SMIG: Situación, Mecanismo, Implicación, Gotcha
Deja de escribir docs que solo dicen "esta función suma dos números". Un comentario o paso de recorrido que narra el código aporta cero información: el lector ya está mirando el código. Nadie relee lo que el código ya muestra. Un buen onboarding invierte sus palabras en las partes que no se ven: por qué está construido así, qué se rompe si lo tocas mal. La regla SMIG es una lista de verificación que obliga a cada paso del doc a ganarse su espacio.
Las cuatro partes
Escribe cada paso de un doc, code tour o guía de onboarding contra cuatro preguntas:
| Parte | Pregunta que responde | Línea de ejemplo |
|---|---|---|
| Situación | ¿Qué estamos viendo? | "Este es el bucle de reintentos que envuelve cada llamada de pago saliente." |
| Mecanismo | ¿Cómo funciona? | "Hace backoff exponencial: 1s, 2s, 4s, con tope en 30s." |
| Implicación | ¿Por qué importa? | "Sin el tope, un gateway caído congelaría el checkout durante minutos." |
| Gotcha | ¿Qué te muerde? | "El reintento NO es seguro ante no-idempotencia — nunca envuelvas llamadas a charge() con él." |
Situación y Mecanismo deben ser cortos — una línea cada uno suele bastar, porque el código carga con la mayor parte. Implicación y Gotcha es donde vive el conocimiento invisible, así que ahí va el presupuesto de palabras.
Por qué fallan los docs de "suma dos números"
El código ya responde qué y (en gran parte) cómo. Lo que nunca puede responder:
- La alternativa descartada. "Primero probamos una cola aquí; se bloqueaba bajo carga." Una oración le ahorra al siguiente ingeniero una semana de redescubrimiento.
- El radio de impacto. ¿Qué llamadores dependen de este comportamiento? ¿Qué se rompe dos servicios más allá?
- La trampa. El parámetro que parece opcional pero no lo es. La función que es segura en todos lados excepto dentro de una transacción.
Una prueba de olfato útil: si borraras el código y conservaras solo tu doc, ¿el doc seguiría diciendo algo? "Suma dos números" no dice nada. "Redondea los medios centavos hacia el comerciante según la auditoría de facturación de 2019" sobrevive.
El curso de escritura técnica de Google plantea la misma idea como una ecuación: la buena documentación es el conocimiento que tu audiencia necesita menos el que ya tiene. Para un lector con el código abierto, Situación y Mecanismo son en su mayoría "ya lo tiene" — Implicación y Gotcha son la brecha.
Presupuesta tus palabras como un revisor presupuesta su atención
- Situación: 1 oración. Orienta, no pasees.
- Mecanismo: 1–2 oraciones. Solo lo que el código oculta (concurrencia, orden, estado escondido).
- Implicación: 2–3 oraciones. Consecuencias, dependencias, el "o si no".
- Gotcha: tantas como honestamente tengas. Esta es la sección que la gente captura en pantalla.
Si un paso termina siendo 80% Situación y Mecanismo, o el código necesita un renombre más que un doc — o estás narrando.
Nivel avanzado: SMIG también es un prompt
La regla funciona además como instrucción para asistentes de codificación con IA. Pídele a tu asistente "escribe un code tour de este módulo donde cada parada cubra Situación, Mecanismo, Implicación y Gotcha" y obtendrás una salida estructuralmente mejor que con "documenta este código" — porque el modelo, como un ingeniero junior, por defecto narra lo que ve. La rúbrica lo obliga a razonar sobre consecuencias y casos límite.
- CodeTour (VS Code): graba un recorrido guiado donde cada parada sea un bloque SMIG; el tour se reproduce dentro del editor, junto al código vivo.
- Compuerta de revisión: cuando llegue un PR de documentación, comenta "¿dónde está la G?" en cualquier paso sin gotcha. O aparece una real, o el autor confirma que el paso está genuinamente libre de trampas — ambos resultados son victorias.
Y mantenlo mínimo: la guía de mejores prácticas de documentación de Google lo llama "minimum viable documentation" — un conjunto pequeño de docs frescos y precisos vence a una colección extensa de docs en distintos estados de deterioro.
Recursos
- Audience — Google Technical Writing One (la ecuación de "lo necesario menos lo conocido")
- Documentation Best Practices — Google style guide (minimum viable documentation)
- Explanation — Diátaxis (el tipo de doc para contexto y "por qué importa")
- A beginner's guide to writing documentation — Write the Docs
- CodeTour — graba y reproduce recorridos guiados en VS Code
¿Construyendo una funcionalidad con IA? Yeda AI diseña, audita y entrega sistemas LLM de producción.