Documentar para mi 'yo' del futuro: el único sistema que he logrado mantener
Cansado de sistemas de documentación que nunca usas? Descubre un método simple basado en Markdown y Git para crear una base de conocimiento que tu 'yo' del futuro realmente agradecerá.
He intentado de todo. Wikis corporativas, Notion, Confluence, repositorios de Google Docs, hasta cuadernos físicos. Todos empiezan con la mejor de las intenciones y terminan como cementerios de información desactualizada. ¿El problema? La fricción.
Cada vez que tenía que documentar algo, implicaba abrir otra app, navegar a la página correcta, luchar con un editor que no era el mío y, al final, crear algo que nadie, ni siquiera yo, volvería a consultar. El sistema era el enemigo.
La epifanía llegó cuando me pregunté: ¿Para quién estoy escribiendo esto? La respuesta casi nunca es 'para el equipo' o 'para un nuevo desarrollador'. El 90% de las veces, es para mi 'yo' del futuro. Ese pobre tipo que en seis meses abrirá el proyecto, no recordará nada y estará bajo presión.
Mi 'yo' del futuro no necesita un wiki bonito. Necesita respuestas. Rápido. Y necesita confiar en que esas respuestas son correctas.
Así nació mi sistema. Es aburridamente simple, y por eso funciona.
El Sistema: Markdown, Git y un Directorio `docs/`
Mi sistema se basa en dos principios:
1. La documentación vive donde vivo yo: En mi editor de código, cerca del código fuente. 2. La herramienta es el menor de los problemas: Usa texto plano (Markdown) y control de versiones (Git).
Para cada proyecto
Dentro de cada repositorio de código, creo un directorio `docs/`. No más, no menos. Dentro de ese directorio, tengo una estructura predecible:
* `docs/01-setup.md`: Instrucciones para levantar el proyecto desde cero. Asumo que mi 'yo' del futuro ha sufrido una amnesia total. Incluyo variables de entorno, comandos de instalación, y cómo correr los tests. Todo lo que necesito para pasar de `git clone` a un entorno funcional.
* `docs/02-arquitectura.md`: Un resumen de alto nivel. No escribo un tratado. A menudo es un simple diagrama en ASCII o un enlace a un Excalidraw, explicando los componentes principales y cómo se hablan entre ellos. ¿Es un monolito con una base de datos? ¿Son tres microservicios y una cola de mensajes? Eso es todo.
* `docs/03-decisiones.md`: Esta es la joya de la corona. Un log de decisiones de arquitectura (ADR - Architecture Decision Record, pero en versión ultra-ligera). Cada vez que tomo una decisión importante, añado una entrada con fecha: * Contexto: ¿Qué problema estaba resolviendo? * Decisión: ¿Qué elegí? (Ej: 'Usar PostgreSQL en lugar de MongoDB'). * Consecuencias: ¿Por qué? ¿Qué ganamos y qué perdemos? ('Elegimos Postgres por las transacciones ACID, a pesar de que el esquema es menos flexible'). Este archivo me ha salvado de innumerables horas de preguntarme '¿en qué demonios estaba pensando?'.
* `docs/cheatsheet.md`: Comandos útiles, snippets de código, consultas SQL recurrentes, ejemplos de `curl` para probar los endpoints. Todo lo que uso en el día a día y que me da pereza volver a escribir.
Para mi cerebro digital general
Para todo lo que no pertenece a un proyecto específico (configuración de mi entorno, notas sobre nuevas tecnologías, procesos de DevOps), tengo un repositorio privado en GitHub llamado `mi-cerebro`. Es, literalmente, una colección de archivos Markdown organizados por carpetas (`/devops`, `/herramientas`, `/ideas`).
¿Por qué este sistema sí funciona?
1. Cero Fricción: Ya estoy en VS Code. Crear o editar un archivo `.md` es instantáneo. No hay cambio de contexto. 2. Versionado y Contextual: La documentación evoluciona con el código. Puedo hacer `git blame` a un archivo de documentación para ver cuándo y por qué cambió una decisión. Está en el mismo Pull Request que el código que la necesita. 3. Agnóstico a la Herramienta: Es solo texto. Puedo usar `grep`, `rg` (ripgrep), el buscador de VS Code, Obsidian, o cualquier cosa que lea archivos de texto. No estoy atado a ninguna plataforma. 4. Búsqueda Fulminante: `Cmd+Shift+F` en mi editor de código es mi base de datos de conocimiento. Es la forma más rápida de encontrar lo que necesito, ya sea en el proyecto actual o en mi 'cerebro' general.
Deja de construir catedrales de documentación que nunca visitas. Construye un taller funcional y con capacidad de búsqueda para ti mismo. Tu 'yo' del futuro, estresado y con la memoria en blanco, te lo agradecerá.