Monolito

Última actualización: 06-01-2026 09:01 PM

Contexto — pDOCS

1) Qué es pDOCS

pDOCS es la web de documentación donde voy a documentar todos mis proyectos. Su objetivo es mantener una estructura clara para:

• continuar el trabajo sin perder contexto,
• y dejar el conocimiento registrado para estudiarlo después.

2) Para qué lo usamos

• Retomar rápido un proyecto sin reconstruir mentalmente “qué era esto”.
• Registrar conocimiento (ideas, estructura, decisiones) para aprender y revisar.
• Trabajar con asistencia (por ejemplo, generación de código) sin que el proyecto dependa de lo que recordamos en el chat.

3) Ficha técnica

• Framework: Astro + Starlight.
• Build: SSG (estático).
• Contenido: Markdown/MDX en src/content/docs/.
• Hosting: Vercel (deploy desde GitHub).
• Dominio: docs.raulnivelazo.com (DNS en Cloudflare → Vercel).
• Búsqueda: Starlight/Pagefind (atajo Ctrl + K).

4) Reglas base (cómo está pensado)

4.1 Multi-proyecto

pDOCS es un solo sitio que contiene múltiples proyectos, cada uno bajo:

• /proyectos/<slug>/...

Esto mantiene todo en un lugar y evita tener varias webs de documentación separadas.

4.2 Mantenerlo simple (no hacerlo “una app”)

La intención es que pDOCS se mantenga como documentación estática.

Por defecto:

• sin backend propio,
• sin cuentas/roles,
• sin base de datos,
• sin features extra salvo que aporten valor real.

4.3 Idiomas (decisión)

• Empezamos solo en Español.
• Español vive en la raíz (sin /es).
• Inglés, si llega, vive bajo /en/..., respetando la misma estructura.

Regla editorial: no traducir “a medias”: si un proyecto tiene /en/, mínimo debe tener portada equivalente y navegación básica.

4.4 Visibilidad en el sidebar (decisión)

A veces quiero que una página exista y sea accesible por URL, pero no aparezca en la navegación lateral mientras está en construcción (o porque es interna).

Regla: una página puede ocultarse del sidebar con frontmatter (sin dejar de existir en la web).

4.5 Búsqueda (decisión)

• Global (siempre): la búsqueda principal es global (Ctrl + K).

• Por proyecto (opcional): cuando aporte valor, cada proyecto puede tener una página:

  • /proyectos/<slug>/buscar/

Esa página sirve para buscar solo dentro de ese proyecto, sin cambiar la búsqueda global.

5) Archivos clave (para ubicar dónde se configura qué)

• Config del sitio y navegación: /astro.config.mjs.
• Esquema/validación de frontmatter: /src/content.config.ts.
• Contenido (rutas del sitio): /src/content/docs/**.

6) Cómo avanzamos (método)

El progreso del proyecto se refleja en:

• reescribir y mejorar estos documentos,

• mover contenido a su lugar correcto,

• mantener coherentes los tres monolitos:

  • Contexto (este documento)
  • Modularidad (cómo funciona y cómo operarlo)
  • Backlog (prioridades: qué falta y en qué orden)

7) Decisiones (ADR) — concepto simple

Cuando tomemos una decisión importante que afecte el futuro del sistema, se registra como un ADR (Architecture Decision Record): un documento corto que explica:

• el contexto,
• las opciones,
• la decisión tomada,
• y sus consecuencias.

Esto evita re-discutir lo mismo cuando se retome el proyecto.

8) Cómo esto ayuda a trabajar con un LLM

Si estos tres monolitos están bien mantenidos:

• El LLM puede retomar el proyecto leyendo primero Contexto.
• Luego puede operar y proponer cambios concretos sobre Modularidad.
• Y puede priorizar trabajo según Backlog.

Nota práctica: los diagramas deben tener un formato que sea legible tanto por humanos como por herramientas (ver Modularidad → Diagramas).