Skip to main content

Contexto​

Una vez creada la organización (ver ADR-0001), surge la necesidad inmediata de documentar productos, glosario, runbooks, decisiones y procesos internos. Sin un hogar definido, esa información se distribuye en READMEs, hilos de chat, documentos sueltos y memorias individuales. Necesitamos un mecanismo único de búsqueda y referencia que sirva tanto a personas como a agentes de IA que colaboran en el proyecto.

A esto se suma el requisito de privacidad: el contenido habla de productos en desarrollo, decisiones internas e infraestructura sensible, así que el hosting tiene que estar detrás de autenticación real, no simplemente "no listado".

Decisión​

Creamos el repo eigenoid/internal-docs como hogar único de la documentación interna del proyecto (productos, glosario, runbooks, ADRs, ops), construido con Docusaurus y desplegado en Cloudflare Pages detrás de Cloudflare Access (Zero Trust Free, GitHub como IdP).

Consecuencias​

  • Una sola fuente de verdad: cualquier persona o agente sabe dónde buscar y dónde escribir documentación.
  • Docs-as-code: el contenido vive en Markdown junto a su historia git; los cambios se revisan vía PR igual que el código.
  • Tooling de Docusaurus: sidebar autogenerado, búsqueda local, versioning y theming sin construirlo a mano.
  • Hosting privado real: Cloudflare Access garantiza que solo miembros autenticados con GitHub vean el sitio, lo que GitHub Pages en plan Free/Team no ofrece (siempre sirve público).
  • Costo de toolchain Node: contribuir requiere node + npm, lo que añade fricción para escritores no técnicos.
  • Acoplamiento a Docusaurus: migrar a otra herramienta en el futuro implica trabajo (frontmatter, MDX, plugins propios). Asumimos el lock-in conscientemente.

Alternativas evaluadas​

  • Notion / Confluence / Google Docs: editor más amigable, pero rompen docs-as-code (no hay PRs, ni history granular, ni búsqueda integrada con el código). Además son SaaS de pago para uso serio.
  • READMEs distribuidos en cada repo: cero infraestructura, pero la documentación queda fragmentada y duplicada; no hay índice global ni búsqueda.
  • Otros SSGs (MkDocs, Astro Starlight, Nextra): comparables en features, pero el equipo ya conoce React/Docusaurus y su ecosistema de plugins es más maduro.
  • GitHub Pages: gratis y nativo, pero siempre sirve público en planes Free/Team; bloqueador directo para docs internas confidenciales.

Referencias​