Documentación bien organizada

Una herramienta muy útil y más rápida que tener un chat al que hacerle preguntas es tener una documentación bien organizada y bien indexada.

Por supuesto, hay mil herramientas para esto y cada programador puede usar la que prefiera. En mi opinión, es útil no sobre documentar las cosas. Muchas cosas ya traen su propia documentación, así que documentar solo lo que realmente necesita contexto o explicación extra. Esto dependerá ya de tus gustos y de las necesidades de tu equipo.

Yo recomiendo usar Obsidian: https://obsidian.md/. Porque corre en local, te lo puedes instalar y consiste en un árbol de carpetas y archivos Markdown.

Ejemplo Organización

Un ejemplo de cómo organizo yo las carpetas:

docs/
├── 00-inicio/
│   └── index.md
├── 01-arquitectura/
│   ├── 01-decisiones.md
│   └── 02-diagramas.md
├── 02-apis/
│   ├── 01-autenticacion.md
│   ├── 02-usuarios.md
│   └── 03-pagos.md
├── 03-despliegue/
│   ├── 01-desarrollo.md
│   ├── 02-staging.md
│   └── 03-produccion.md
├── 04-guias/
│   ├── 01-setup-local.md
│   ├── 02-testing.md
│   └── 03-troubleshooting.md
└── 05-referencias/
    ├── 01-librerias.md
    └── 02-enlaces-externos.md

Cada uno se organiza las carpetas como quiera. La ventaja es que si controlas Markdown, es muy fácil ponerle estilos a nuestros documentos. Títulos, listas, enlaces, tablas, bloques de código… suficiente para cualquier documentación técnica.

Si quieres aprender un poco sobre Markdown, aquí tienes su guía: https://www.markdownguide.org/. Pero en resumen, no dejan de ser notas vitaminadas que no tienen nada que envidiar a las apps de documentos como Word. Y es sencillo y gratis.

Mi documentación

Yo por mi parte he ido actualizando lo que son mis docs públicos. No deja de ser una web estática y tienes el código de cómo funciona abajo:

• https://github.com/jramma
• https://docs.casset.cat/

Está hecho con Starlight: https://starlight.astro.build/. Porque sigue la misma estructura: la carpeta docs y ahí es lo mismo que en Obsidian, una carpeta con la jerarquía que quiera poner. Así lo que escribo localmente lo puedo publicar sin tener que reorganizar nada.

Y la indexación rápida y buscador que me facilita la vida es Pagefind: https://pagefind.app/. Está basado en Rust y la verdad es que funciona muy bien. Cuando entras en https://docs.casset.cat/ haces Ctrl+K y puedes encontrar lo que necesites rápidamente. Sin servidores, sin costes, sin complicaciones.