Contexto
Llevaba meses documentando proyectos solo con Markdown. Funciona bien para texto: decisiones, listas de componentes, snippets de codigo. Pero cuando intento explicar una arquitectura de varias capas o un flujo de decision con bifurcaciones, el Markdown se convierte en un muro de texto con flechas ASCII que ni yo entiendo al releerlo.
Un dia probe generar diagramas SVG como complemento al MD. Los puse en la raiz del proyecto junto al documento principal. Lo que no esperaba: cuando otra IA leyo el SVG como contexto, lo entendio perfectamente. No como imagen -- lo parseo como documento estructurado. Entendio las capas, las conexiones, las dependencias. Mejor de lo que yo esperaba.
Lo que aprendi
La clave es que Markdown y SVG son complementarios, no redundantes. El MD explica el "que" y el "por que" en detalle. El SVG muestra el "como se conecta" de un vistazo.
Para que se entienda bien, voy a usar un ejemplo que no tiene nada que ver con software: como hacer una carlota de limon. Si puedes documentar un postre con MD + SVG, puedes documentar cualquier sistema.
Markdown: el manual de referencia
## Carlota de limon
> Postre clasico mexicano. Sin horno, sin complicaciones.
### Ingredientes
| Ingrediente | Cantidad | Nota |
|------------|----------|------|
| Galletas Maria | 2 paquetes | la base de todo |
| Leche condensada | 1 lata (397g) | **no reducir** |
| Media crema | 1 lata (225g) | o crema para batir |
| Jugo de limon | 1 taza (~8 limones) | recien exprimido |
| Ralladura | 2 limones | solo la parte verde |
### Pasos
1. **Mezclar** leche condensada + media crema + jugo de limon
2. **Remojar** galletas en jugo diluido (`2 segundos`, no mas)
3. **Armar** capas: galleta → mezcla → galleta → mezcla (x3)
4. **Refrigerar** minimo 4 horas — *mejor toda la noche*
5. **Decorar** con ralladura y galleta triturada
### Tips
- Si remojas las galletas mas de 2 segundos se **deshacen**
- La mezcla espesa sola gracias al acido del limon
(no necesitas grenetina ni nada extra)
- Para version *fancy*: agregar una capa de `mermelada de zarzamora`
---
*Tiempo total: 20 min + 4 hrs refrigeracion*
Carlota de limon
Postre clasico mexicano. Sin horno, sin complicaciones.
Ingredientes
| Ingrediente | Cantidad | Nota |
|---|---|---|
| Galletas Maria | 2 paquetes | la base de todo |
| Leche condensada | 1 lata (397g) | no reducir |
| Media crema | 1 lata (225g) | o crema para batir |
| Jugo de limon | 1 taza (~8 limones) | recien exprimido |
| Ralladura | 2 limones | solo la parte verde |
Pasos
- Mezclar leche condensada + media crema + jugo de limon
- Remojar galletas en jugo diluido (
2 segundos, no mas) - Armar capas: galleta, mezcla, galleta, mezcla (x3)
- Refrigerar minimo 4 horas — mejor toda la noche
- Decorar con ralladura y galleta triturada
Tips
- Si remojas las galletas mas de 2 segundos se deshacen
- La mezcla espesa sola gracias al acido del limon (no necesitas grenetina ni nada extra)
- Para version fancy: agregar una capa de
mermelada de zarzamora
Tiempo total: 20 min + 4 hrs refrigeracion
Fijate cuanto se puede comunicar con puro texto plano: headers, tablas, bold, italicas, code inline, blockquotes, listas, lineas divisoras. Cualquier editor, celular o terminal lo abre. Git lo diffea linea por linea. Una IA lo parsea sin problema.
Pero el proceso (mezclar, remojar, capas, refrigerar) es secuencial con bifurcaciones -- y eso es dificil de ver en una lista numerada. Ahi es donde entra el SVG.
SVG: el mapa visual
Ahora el mismo proceso pero como diagrama.
<svg viewBox="0 0 600 320" xmlns="http://www.w3.org/2000/svg">
<title>Flujo para preparar Carlota de limon</title>
<desc>5 pasos desde ingredientes hasta postre listo</desc>
<!-- Ingredientes (3 entradas paralelas) -->
<rect x="10" y="10" width="120" height="50" rx="8"
fill="#FEF3C7" stroke="#D97706"/>
<text x="70" y="32" text-anchor="middle"
font-size="11" fill="#92400E">Leche condensada</text>
<text x="70" y="48" text-anchor="middle"
font-size="11" fill="#92400E">+ media crema</text>
<rect x="10" y="80" width="120" height="50" rx="8"
fill="#ECFCCB" stroke="#65A30D"/>
<text x="70" y="108" text-anchor="middle"
font-size="12" fill="#3F6212">Jugo de limon</text>
<rect x="10" y="150" width="120" height="50" rx="8"
fill="#FEE2E2" stroke="#DC2626"/>
<text x="70" y="178" text-anchor="middle"
font-size="12" fill="#991B1B">Galletas Maria</text>
<!-- Flechas hacia mezcla -->
<line x1="130" y1="35" x2="178" y2="80" stroke="#888"/>
<line x1="130" y1="105" x2="178" y2="95" stroke="#888"/>
<!-- Paso 1: Mezclar -->
<rect x="180" y="66" width="140" height="56" rx="8"
fill="#E1F5EE" stroke="#0F6E56"/>
<text x="250" y="88" text-anchor="middle"
font-size="13" font-weight="500" fill="#085041">
Mezclar</text>
<text x="250" y="106" text-anchor="middle"
font-size="10" fill="#085041">
hasta consistencia cremosa</text>
<!-- Paso 2: Remojar galletas -->
<line x1="130" y1="175" x2="178" y2="175" stroke="#888"/>
<rect x="180" y="148" width="140" height="56" rx="8"
fill="#E6F1FB" stroke="#185FA5"/>
<text x="250" y="170" text-anchor="middle"
font-size="13" font-weight="500" fill="#0C447C">
Remojar</text>
<text x="250" y="188" text-anchor="middle"
font-size="10" fill="#0C447C">
2 seg en jugo diluido</text>
<!-- Flechas hacia armado -->
<line x1="320" y1="94" x2="368" y2="125" stroke="#888"/>
<line x1="320" y1="176" x2="368" y2="145" stroke="#888"/>
<!-- Paso 3: Armar capas -->
<rect x="370" y="108" width="120" height="56" rx="8"
fill="#EEEDFE" stroke="#534AB7"/>
<text x="430" y="130" text-anchor="middle"
font-size="13" font-weight="500" fill="#3C3489">
Armar capas</text>
<text x="430" y="148" text-anchor="middle"
font-size="10" fill="#3C3489">
galleta + mezcla x3</text>
<!-- Paso 4: Refrigerar -->
<line x1="430" y1="164" x2="430" y2="200" stroke="#888"/>
<rect x="355" y="202" width="150" height="56" rx="8"
fill="#E0F2FE" stroke="#0284C7"
stroke-dasharray="6 3"/>
<text x="430" y="224" text-anchor="middle"
font-size="13" font-weight="500" fill="#0C4A6E">
Refrigerar</text>
<text x="430" y="242" text-anchor="middle"
font-size="10" fill="#0C4A6E">
4 hrs min (mejor 8 hrs)</text>
<!-- Paso 5: Servir -->
<line x1="430" y1="258" x2="430" y2="278" stroke="#888"/>
<rect x="370" y="280" width="120" height="36" rx="18"
fill="#FEF3C7" stroke="#D97706"/>
<text x="430" y="302" text-anchor="middle"
font-size="13" font-weight="600" fill="#92400E">
Carlota lista</text>
</svg>
Es el mismo archivo de texto plano. Pesa menos que un PNG. Git lo diffea. Un navegador lo renderiza bonito. Y una IA lo lee como documento estructurado: ve tres ingredientes, dos flujos paralelos que convergen, una secuencia de pasos, y un nodo final. Todo sin ver una sola flecha -- lo infiere del XML.
Ahora imagina que en vez de un postre, el diagrama muestra las capas de una API, un flujo de decision de un chatbot, o las fases de un proyecto. Mismo formato, misma tecnica.
Un archivo, dos lecturas
Esto es lo mas interesante: un humano y una IA leen el mismo SVG de formas completamente distintas, y ambos lo entienden.
Tu ves cajas de colores y flechas. Seguiste el flujo de la carlota de izquierda a derecha: ingredientes entran, se mezclan, se arman las capas, al refrigerador. Las flechas te guiaron. Los colores te agruparon cosas (amarillo = ingredientes lacteos, verde = limon, rojo = galletas).
La IA no vio nada de eso. Leyo XML. Parseo cada <rect> como un nodo con posicion y dimensiones. Cada <text> como contenido semantico. Cada <line> como una relacion entre coordenadas. Los atributos <title> y <desc> le dieron contexto extra que tu ni ves en pantalla. Inferio que "Leche condensada" y "Jugo de limon" convergen en "Mezclar" porque las lineas apuntan al mismo rectangulo.
El resultado:
- Las flechas son para el humano
- El orden del XML y los textos son para la IA
- Los colores son para el humano (agrupan visualmente)
- Las coordenadas y posiciones son para la IA (infiere jerarquia)
Y como todo esta en el mismo archivo, nunca se desincronizan. No hay un diagrama en Figma que dice una cosa y un documento que dice otra. Una sola fuente de verdad con dos interfaces de lectura.
La receta practica (ahora si de software)
Para documentar un proyecto para que tanto humanos como IAs lo entiendan rapido:
- Un MD en la raiz con: que es, por que existe, que decide cada componente, que stack usa
- Un SVG por cada concepto que tenga relaciones espaciales: capas de arquitectura, flujos de decision, fases de proyecto
- Ambos en la raiz del repo, ambos versionados en git, ambos diffeables
Los dos formatos son abiertos, pesan kilobytes, y se leen en cualquier computadora o celular con un editor de texto. El SVG ademas se renderiza bonito en cualquier navegador. No necesitas Figma, Lucidchart ni Mermaid -- un archivo de texto con angulos y coordenadas.
Lo que me sorprendio es que nunca habia pensado en los SVGs como documentacion. Siempre los vi como "imagenes vectoriales para logos". Resulta que son documentos estructurados que comunican relaciones mejor que cualquier lista de bullets. Y las IAs los entienden de primera.