Cómo se mantiene esta doc
De dónde sale el contenido, cómo se actualiza, cómo evitamos que mienta y quién es dueño de cada área.
Esta doc es la capa publicable y curada de la fuente de verdad, no la fuente misma. Esta página cuenta cómo se produce, cómo se actualiza y, sobre todo, cómo evitamos que se desactualice y termine mintiendo. Es para quien contribuya a la doc (hoy el CTO, a futuro el equipo).
De dónde sale el contenido
La verdad primaria vive en el trabajo real: las specs, las decisiones y el código. Ahí se piensa, se discute y se resuelve. Esa capa es densa y no está hecha para leerse de corrido.
Lo que ves aquí es ese trabajo destilado y curado para el equipo: el mismo conocimiento, ordenado para leerse: la vista publicable de la fuente primaria, que vive en otro lado.
Cómo se actualiza
Es un sitio Astro en un repositorio (heyaxel/handbook). Actualizar la doc es
editar los archivos .mdx y desplegar.
Hoy la doc la mantiene el CTO: edita los .mdx y despliega. El circuito es
corto a propósito mientras el equipo es pequeño.
A medida que el equipo crezca, las contribuciones entran como pull requests al repositorio, con revisión antes de desplegar.
Los índices de búsqueda y de IA
El sitio tiene dos capas que leen el contenido y hay que refrescarlas tras un cambio importante. Ninguna se reconstruye sola: son un paso manual, como el deploy.
El buscador es un índice de Pagefind que se genera en el build. En local se
refresca con pnpm index; en producción se hornea en cada pnpm build.
El asistente responde sobre un índice vectorial en Cloudflare (Vectorize).
Tras cambiar contenido, corré pnpm ai:index para reindexarlo: trocea las
páginas, las embede y las sube. Si no lo corrés, la IA responde con la
versión vieja del contenido.
pnpm ai:index necesita CLOUDFLARE_ACCOUNT_ID y CLOUDFLARE_API_TOKEN en el
entorno (permisos: Workers AI Read + Vectorize Edit). Se hace desde la máquina de
quien despliega, igual que el deploy.
Cómo evitamos que mienta
El riesgo de toda doc es quedar desfasada del producto. Estas son las reglas que lo contienen:
Cuando el código o una decisión cambian de forma sustancial, se actualiza la página afectada como parte del mismo trabajo, no después.
Las páginas de arquitectura dicen “diseño aprobado” a propósito hasta que la pieza se construya. El estado real de cada área vive en Estado de la plataforma.
El contenido legal lleva un badge de pendiente de validación hasta que un abogado lo valide. Marcar lo no validado es preferible a publicarlo como si fuera firme.
Dueño por área
Cada área de la doc tiene un dueño responsable de que su contenido sea correcto y esté al día. Son roles, no personas:
| Área | Dueño | Cómo se contribuye |
|---|---|---|
| Knowledge Base | CTO | Cualquiera abre un PR; el dueño lo revisa y aprueba. |
| Engineering | CTO | Los devs editan y abren PR; el CTO aprueba el merge. |
| Legal | Curador legal y CTO | Cambios de contenido jurídico los valida el curador legal antes del merge. |
| Producto | CTO y marketing | PR abierto; lo aprueba quien corresponda según sea técnico o de mensaje. |
El curador legal valida el contenido de dominio; el CTO lo publica y lo mantiene en forma. Nada legal se da por firme sin validación.
KB y Engineering son responsabilidad del CTO, que es quien conoce el estado real del código y la arquitectura.
Reportar algo desactualizado
Si encuentras algo que no cuadra con la realidad, no hace falta abrir un ticket: en el pie de cada página hay un enlace de feedback para reportarlo directamente.
El pie de cada página incluye un enlace para reportar contenido desactualizado o incorrecto. Es la vía más rápida para que el dueño del área lo corrija.