Documentos corporativos

Un acta de reunión tiene una parte que es texto —lo que se discutió, por qué se decidió algo— y una parte que son datos: quién asistió, qué acciones quedaron abiertas, para cuándo y a cargo de quién. En la práctica las dos partes acaban en el mismo documento de texto, y los datos se recuperan después leyendo: alguien repasa las actas del trimestre para saber qué acciones siguen abiertas, o copia los estados de veinte informes a una hoja de cálculo.

El problema no es el formato del texto sino que los datos no están marcados como tales. STXT resuelve exactamente eso: los datos son nodos con nombre y valor, el texto va en bloques literales, y el documento sigue leyéndose de arriba abajo como siempre.

Un acta de reunión

El acta de una reunión semanal, tal como la escribiría quien la toma:

Minutes (com.acme.corp.minutes):
	Title: Sincronización semanal — Plataforma
	Date: 2026-01-09
	Duration minutes: 45
	Attendees:
		Attendee: Joan Costa
		Attendee: Mery Adams
		Attendee: Keyla Brown

	Notes >>
		El roadmap del trimestre va según lo previsto, pero falta cerrar la
		capacidad del equipo para febrero. El riesgo principal sigue siendo la
		dependencia del proveedor externo en el módulo X: los tiempos de respuesta
		varían demasiado entre días.

		Se acuerda mover la ventana de despliegue del viernes al lunes, para tener
		soporte completo el día siguiente. Se revisará el coste de la opción B
		antes de decidir sobre la caché.

	Decisions:
		Decision: Mover la ventana de despliegue al lunes
			Id: DEC-0142
			Decision status: Approved
			Owner: Platform Team
			Rationale >>
				Reduce el riesgo operativo: el soporte del martes es completo y el del
				sábado no.
		Decision: Congelar cambios no críticos en el módulo X
			Id: DEC-0143
			Decision status: Proposed
			Owner: Reliability

	Actions:
		Action: Preparar la propuesta de capacidad del trimestre
			Id: ACT-0991
			Owner: Mery Adams
			Due: 2026-01-16
			Action status: Open
		Action: Estimar el coste de la opción B
			Id: ACT-0992
			Owner: Joan Costa
			Due: 2026-01-14
			Action status: In Progress

Se lee como un acta. Y a la vez, para un programa, es un árbol en el que cada acción tiene un responsable, una fecha y un estado.

Qué es dato y qué es texto

La única decisión de modelado que hay que tomar es esa, y el criterio es práctico: es dato lo que alguien va a buscar, filtrar o contar; es texto lo demás.

• Los asistentes, las decisiones y las acciones son datos: se listan, se cruzan con otras actas, se vencen. Van en nodos inline, uno por elemento.
• El resumen de la discusión y la justificación de cada decisión son texto: se leen, no se procesan. Van en bloques >>, donde se escriben párrafos sin ninguna restricción.
• El título de cada decisión y de cada acción es el valor del propio nodo (Decision: Mover la ventana…), y sus atributos son hijos. Así la lista se lee de un vistazo.

Si más adelante hace falta procesar algo que hoy es texto —por ejemplo, los riesgos mencionados en las notas—, se saca a un nodo propio. El documento no cambia de formato; gana un nodo.

La plantilla

Una plantilla fija qué debe tener toda acta y qué es opcional, y acota los estados:

Template (@stxt.template): com.acme.corp.minutes
	Description >>
		Minutes: Acta de reunión
		Decisions: Decisiones tomadas o propuestas en la reunión
		Actions: Acciones acordadas, con responsable y fecha límite
	Structure >>
		Minutes:
			Title: (1)
			Date: (1) DATE
			Duration minutes: (?) NATURAL
			Attendees: (1)
				Attendee: (+)
			Notes: (?) TEXT
			Decisions: (?)
				Decision: (*)
					Id: (1)
					Decision status: (1) ENUM [Proposed, Approved, Rejected]
					Owner: (?)
					Rationale: (?) TEXT
			Actions: (?)
				Action: (*)
					Id: (1) @Id
					Owner: (?) @Owner
					Due: (?) DATE
					Action status: (1) ENUM [Open, In Progress, Done, Blocked]

Lo que garantiza, acta a acta:

• Toda acta tiene título, fecha y al menos un asistente; sin eso no valida.
• Una decisión está en uno de tres estados, y una acción en uno de cuatro. Un estado escrito de otra manera (Aprobada, open) es un error, no una variante.
• Las fechas son fechas: 2026-01-32 no pasa.
• Un nodo que no está en la plantilla —Atendees con una sola t, un Priority que alguien añadió por su cuenta— se rechaza. Es el modelo de contenido cerrado: la plantilla es la lista completa de lo que puede aparecer.
• Id y Owner se declaran una vez y se reutilizan con @Id y @Owner: dentro de un namespace, un nombre de nodo identifica un solo nodo. Por la misma regla, el estado de una decisión y el de una acción son nodos distintos —Decision status y Action status—: sus listas de valores no coinciden, y un mismo nombre no puede tener dos definiciones.

La plantilla se guarda en el directorio .stxt/ del repositorio donde viven las actas, y a partir de ahí el editor y la línea de comandos la aplican sin configurar nada (El entorno de trabajo).

Un informe de estado

El mismo enfoque sirve para cualquier documento periódico. Un informe de estado semanal:

Status Report (com.acme.corp.status):
	Project: Portal de clientes
	Owner: Platform Docs
	Period:
		From: 2026-01-05
		To: 2026-01-09
	Status: Green

	Summary >>
		Avance sostenido en la documentación base. Queda trabajo en las
		herramientas de línea de comandos y en los casos de uso; ninguno bloquea
		la entrega de febrero.

	Progress:
		Item: Página de introducción
			Item status: Done
		Item: Tutorial
			Item status: Done
		Item: Referencia de la línea de comandos
			Item status: In Progress

	Risks:
		Risk: Faltan ejemplos de migración desde otros formatos
			Id: RSK-020
			Level: Medium
			Mitigation >>
				Preparar dos ejemplos de migración antes del cierre del trimestre.

Template (@stxt.template): com.acme.corp.status
	Description >>
		Status Report: Informe de estado periódico de un proyecto
	Structure >>
		Status Report:
			Project: (1)
			Owner: (1)
			Period: (1)
				From: (1) DATE
				To: (1) DATE
			Status: (1) ENUM [Green, Amber, Red]
			Summary: (1) TEXT
			Progress: (?)
				Item: (*)
					Item status: (1) ENUM [Done, In Progress, Blocked]
			Risks: (?)
				Risk: (*)
					Id: (1)
					Level: (1) ENUM [Low, Medium, High]
					Mitigation: (?) TEXT

El semáforo Status es un ENUM, no un adjetivo en el resumen. Con veinte informes en un directorio, un script de diez líneas responde cuántos proyectos están en rojo y cuáles son sus riesgos altos, sin que nadie los haya leído uno a uno.

En el flujo de trabajo

Los documentos viven en un repositorio, como el código:

• Escritura: cualquier editor de texto. Con la extensión de VS Code, la plantilla da autocompletado de nombres y estados, y marca los errores mientras se escribe.
• Revisión: una modificación es un diff de líneas concretas —una acción que pasa de Open a Done, una decisión nueva—, no un fichero binario que hay que abrir para ver qué cambió.
• Integración continua: stxt validate --recursive minutes/ rechaza la incorporación de un acta incompleta o con un estado inválido antes de que llegue al repositorio (La línea de comandos).
• Explotación: el árbol canónico (stxt describe, o la biblioteca de cada lenguaje) alimenta lo que haga falta: la lista de acciones abiertas por persona, un resumen semanal por correo, un panel con los semáforos de todos los proyectos.

Nada de esto obliga a cambiar cómo se escribe: un acta sin plantilla es un documento STXT válido, y la validación se añade cuando el equipo decide qué quiere garantizar.

Límites

STXT estructura el documento; no aporta flujo de aprobación, control de acceso ni notificaciones. Eso lo pone el repositorio y las herramientas de alrededor. Tampoco valida reglas entre campos —que una acción en estado Done no tenga fecha futura, por ejemplo—: esa lógica pertenece a la aplicación que explota los datos, no a la plantilla.

Los géneros vecinos siguen el mismo enfoque: RFCs y propuestas técnicas para documentos con ciclo de vida, y contratos donde los datos viven dentro de texto normativo. El lenguaje que hay detrás de los ejemplos se recorre, regla a regla, en el tutorial.