Documentar para mi 'yo' del futuro: el único sistema que he logrado mantener

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á.