Por qué se empieza por aquí

Todo lo que se construye en este curso —prompts, esquemas, configuraciones, trazas, políticas, documentación de entrega— es texto. La decisión más barata y más duradera que se toma al principio es en qué formato vive ese texto. La respuesta es aburrida y correcta: texto plano.

Tres razones concretas, no de gusto:

1. Se versiona. Git muestra línea por línea qué cambió, quién y cuándo. Con un binario solo muestra «cambió».
2. Lo leen las máquinas y las personas. El mismo .md es la documentación para el cliente, el contexto para el modelo y la fuente de la guía impresa.
3. No depende de nadie. Sin licencia, sin programa propietario, sin versión que se descontinúe.

Markdown: texto plano con lo mínimo de estructura

Markdown es una convención para marcar títulos, listas, énfasis, tablas y código usando solo caracteres del teclado. Se lee sin procesar y se convierte a HTML, PDF o láminas sin esfuerzo.

# Título de nivel 1
## Título de nivel 2

Un párrafo con **negrita**, *cursiva* y `código en línea`.

- Lista con viñetas
- Otro ítem
 - Sub-ítem

1. Lista numerada
2. Segundo paso

| Columna | Otra |
|---|---|
| celda | celda |

```bash
echo "bloque de código con lenguaje declarado"

La versión que se usa en este curso es **CommonMark** con las extensiones de GitHub (tablas,
listas de tareas, código con lenguaje). Es la que entiende el MOOC, Git, los editores y casi
todos los modelos.

> *Markdown* viene de *markup* (lenguaje de marcado) al revés: **marcar hacia abajo**, o sea,
> marcar lo mínimo. El nombre es una broma de su autor, John Gruber (2004).

## Front-matter: metadatos al principio del archivo

Muchas herramientas aceptan un bloque de **YAML** entre dos líneas de `---` al inicio del archivo.
Es donde va lo que describe al documento sin ser el documento:

```markdown
---
titulo: "Asistente documental — ferretería El Tornillo"
version: 0.1
cliente: ferreteria-el-tornillo
verificado: 2026-09
---

# Asistente documental
...

Ese bloque es lo que va a leer el importador del MOOC, el generador de la guía impresa y el propio agente cuando necesite saber de qué trata un archivo. Un mismo texto, varios lectores.

Por qué el texto plano también es la base para el modelo

Un modelo lee tokens (lección siguiente). Todo lo que no es texto —una imagen, un PDF escaneado, una hoja de cálculo con colores— tiene que convertirse a texto antes de que el modelo lo vea, y en esa conversión se pierde información (módulo 7 muestra cuánta). Cuando la fuente ya es texto plano bien estructurado, no hay conversión y no hay pérdida.

De ahí una regla práctica del curso:

Cuándo NO usar Markdown

• Documentos con diagramación exacta y valor legal (un contrato con márgenes, firmas y foliación): se producen en PDF desde una plantilla; el Markdown es el borrador, no la entrega.
• Datos tabulares grandes: una tabla Markdown de 2.000 filas no sirve para nada. Eso es CSV o una base de datos; Markdown solo para la tabla resumen.
• Formularios que llena gente no técnica: nadie va a escribir | celda | a mano. Se les da una interfaz, y la interfaz guarda texto plano por debajo.
• Diagramas complejos: Mermaid (texto → diagrama) sirve hasta cierto tamaño; un plano de red de 40 nodos se dibuja en otra herramienta y se exporta a SVG.

Laboratorio 0.2 · el README del proyecto

El proyecto integrador del curso empieza aquí: una carpeta con un solo archivo. Cada módulo va a añadirle una capa.

mkdir -p ~/labs/el-tornillo && cd ~/labs/el-tornillo
git init -q
cat > README.md <<'EOF'
---
proyecto: asistente-documental
cliente: Ferretería El Tornillo (Bucaramanga)
usuarios: [gerente, contadora, vendedor]
verificado: 2026-09
---

# Asistente documental — Ferretería El Tornillo

## Qué hace (versión 0)
Todavía nada. Este archivo es la primera capa: la descripción del sistema.

## Qué va a hacer
1. Ingerir documentos escaneados (facturas, remisiones, contratos).
2. Extraer campos con esquema y validarlos.
3. Responder consultas citando la fuente.
4. Dejar traza auditable de cada operación.
5. Servir a tres empleados con permisos distintos.

## Perfiles de hardware en los que se prueba
- A · portátil sin GPU dedicada
- B · equipo con 8–16 GB de VRAM
- C · servidor con 24 GB o más
EOF
git add README.md && git commit -qm "Capa 0: descripción del sistema" && git log --oneline

Lo que debe ver: una línea con el hash del commit y el mensaje Capa 0: descripción del sistema.

Entregable: el README.md versionado. De aquí en adelante, cada laboratorio termina con un commit cuyo mensaje empieza por «Capa N».

Qué se degrada en cada perfil

Es el único laboratorio del curso donde los tres perfiles son idénticos. Conviene fijarse en eso: la parte que más dura del sistema es la que menos hardware necesita.

Práctica

1. Convierta a Markdown la última acta o informe que haya escrito en Word. Anote qué se perdió (probablemente nada importante) y qué se ganó.
2. Abra el README.md con tres programas distintos (un editor de código, el bloc de notas, el navegador vía GitHub). Debe leerse en los tres.
3. Escriba el front-matter de un documento del cliente: título, versión, quién lo aprobó, fecha de verificación.

Referencias

1. CommonMark — especificación: https://commonmark.org/ · GitHub Flavored Markdown: https://github.github.com/gfm/
2. Gruber, J. (2004). Markdown. https://daringfireball.net/projects/markdown/ — el documento original.
3. Hunt, A. y Thomas, D. (1999). The Pragmatic Programmer. Addison-Wesley — capítulo «The Power of Plain Text».
4. YAML — especificación 1.2: https://yaml.org/spec/1.2.2/