Una aplicación no empieza con una pantalla. Tampoco empieza con una línea de código. Empieza tomando decisiones.
Antes de crear una funcionalidad, elegir una librería o definir una arquitectura, necesitamos saber qué estamos construyendo, por qué lo estamos construyendo y cómo vamos a mantenerlo cuando el proyecto crezca.
En CraftingBits entendemos el desarrollo de una app como un proceso que empieza mucho antes de programar. Analizamos el proyecto, definimos su alcance, diseñamos la experiencia, construimos una arquitectura que pueda crecer y comprobamos que todo funciona antes de llegar al lanzamiento.
Pero hay una parte de ese proceso que a veces pasa desapercibida: documentar las decisiones que hacen posible todo lo demás. Porque unos meses después nadie debería depender de su memoria para saber por qué una aplicación está construida de una determinada manera. Por eso, antes de programar, construimos también la base documental del proyecto.
La memoria es un mal lugar para guardar decisiones
En cualquier proyecto aparecen cientos de pequeñas decisiones.
Qué arquitectura utilizar.
Qué versión de una librería adoptar.
Cómo se comunican las capas.
Dónde se almacenan determinados datos.
Qué pantallas existen.
Cómo funciona una determinada funcionalidad.
Qué queda pendiente antes de publicar.
Al principio todo parece evidente. El proyecto es pequeño y las decisiones están recientes.
El problema llega unos meses después. O cuando otra persona entra en el proyecto. O cuando hay que recuperar una funcionalidad que se desarrolló hace tiempo.
Sin documentación, continuar el desarrollo implica reconstruir el contexto. Y eso tiene un coste. Se vuelven a discutir decisiones que ya estaban tomadas, se buscan respuestas en conversaciones antiguas y aparecen dudas que podrían haberse evitado con una nota escrita en el momento adecuado.
Por eso tenemos una regla sencilla:
Si una decisión es importante para el proyecto, no debería vivir únicamente en la memoria de una persona.
Dos niveles de documentación
Para evitarlo trabajamos con dos niveles diferentes de documentación. Por un lado está el documento maestro técnico. Por otro, el vault de Obsidian de cada proyecto.
Aunque están relacionados, no cumplen la misma función.
| Documento maestro técnico | Vault de Obsidian | |
|---|---|---|
| Ámbito | Todos nuestros proyectos | Un proyecto concreto |
| Propósito | Definir criterios y estándares | Documentar la realidad del proyecto |
| Contenido | Recomendaciones y reglas | Decisiones y estado actual |
| Ejemplo | Arquitectura recomendada | Arquitectura utilizada |
| Evolución | Cambia con nuestro método | Cambia con la aplicación |
| Objetivo | No empezar de cero | No perder contexto |
La diferencia es importante. El documento maestro puede establecer que trabajamos con versiones estables y soportadas. El proyecto concreto debe registrar qué versiones utiliza realmente. El maestro define el criterio. El vault documenta la aplicación de ese criterio.
Así conseguimos algo que parece sencillo, pero que resulta muy útil: cada proyecto puede beneficiarse de la experiencia acumulada sin convertirse en una copia de otro proyecto.
El documento maestro técnico
El documento maestro es nuestra referencia común. No pretende describir una aplicación concreta. Define los criterios que queremos aplicar cada vez que empezamos un proyecto.
Entre otras cosas, recoge:
- Stack y versiones: lenguaje, SDKs, librerías principales y versiones de referencia.
- Arquitectura: cómo se organizan las capas y responsabilidades.
- Monetización y consentimiento: anuncios, pagos y gestión del consentimiento.
- Requisitos de publicación: privacidad, permisos, formularios de datos y requisitos de las tiendas.
- Testing: qué debemos probar y con qué herramientas.
- Seguridad: gestión de secretos, ofuscación e integridad.
- Publicación: versionado, formato del paquete y checklist de lanzamiento.
No es un documento creado para enseñar cómo trabajamos. Es una herramienta de trabajo. Lo consultamos al comenzar un proyecto y lo actualizamos cuando cambian nuestras herramientas, las plataformas o los requisitos de publicación.
Por eso también hay una regla importante:
El documento maestro se versiona y se fecha.
Una recomendación técnica sin fecha puede quedarse obsoleta. Una decisión fechada permite saber qué criterio estaba vigente cuando se tomó. Ahí también es donde Git entra en juego, facilitando el control de versión y las copias de seguridad.
El vault de Obsidian: la memoria del proyecto
El segundo nivel es mucho más concreto. Cada aplicación tiene su propio vault de Obsidian.
Obsidian nos permite organizar el conocimiento del proyecto en notas relacionadas entre sí, manteniendo una estructura que podemos consultar y ampliar durante todo el ciclo de desarrollo.
La primera pieza es un índice. Su función es sencilla: responder rápidamente a las preguntas básicas.
¿Qué proyecto es?
¿En qué versión está?
¿Qué plataformas soporta?
¿Qué arquitectura utiliza?
¿Qué idiomas tiene?
¿Qué estado tiene actualmente?
Cuando volvemos a un proyecto después de varias semanas o meses, queremos que las primeras respuestas estén a unos segundos de distancia.
A partir de ahí organizamos el vault en diferentes áreas:
- Inicio: información general, datos rápidos y registro de versiones.
- Arquitectura: estructura del proyecto y flujo de datos.
- Pantallas: una nota para cada pantalla.
- Datos: modelos, almacenamiento y reglas.
- Interfaz: navegación, tema y componentes reutilizables.
- Dependencias: stack y versiones exactas.
- Funcionalidades: documentación de las funcionalidades relevantes.
- Monetización: anuncios, pagos y consentimiento.
- Guías de desarrollo: procesos para desarrollar, probar y publicar.
- Plantillas: estructuras reutilizables para mantener la documentación consistente.
No se trata de documentar por documentar. La estructura existe para que encontrar información sea rápido y mantenerla sea sencillo.
Una pantalla, una nota
Una de nuestras reglas es especialmente sencilla:
Una pantalla, una nota. Una funcionalidad, una nota.
Puede parecer una decisión pequeña, pero cambia bastante la forma de trabajar. En lugar de tener un documento enorme donde se mezclan funcionalidades, pantallas y decisiones, cada elemento importante tiene su propio espacio. Eso permite consultar, actualizar y relacionar la información sin tener que recorrer un documento completo.
Además, todas las notas parten de una plantilla común. De esta forma, documentar una nueva pantalla no implica preguntarnos cada vez qué información deberíamos incluir. La estructura ya existe. Y cuando una tarea repetitiva tiene una estructura clara, deja de depender tanto de la memoria y del criterio de quien la realiza.
Documentar también lo que todavía no funciona
Hay otra parte importante de nuestra documentación: no solo registramos lo que está terminado. También documentamos lo que falta.
Una pantalla definida pero todavía no conectada. Una dependencia que se incorporó durante una prueba. Código que ya no se utiliza. Una prueba que sigue siendo provisional. Una decisión pendiente. Un ajuste que queremos realizar antes del lanzamiento.
Esto es especialmente importante porque un proyecto en desarrollo nunca está completamente limpio. Siempre hay algo pendiente. La diferencia está en si sabemos qué es y por qué está ahí.
La deuda que no se documenta se convierte en sorpresa. La deuda documentada se convierte en una tarea.
Y esa diferencia importa mucho cuando un proyecto vuelve a nuestras manos después de un tiempo.
Convertir conocimiento en procesos
La documentación también nos sirve para algo más que consultar información. Nos permite convertir tareas repetitivas en procesos.
Por ejemplo, añadir una pantalla tiene una guía. Publicar una nueva versión tiene otra. Preparar una release puede convertirse en una checklist. Revisar determinados requisitos antes de publicar puede seguir siempre los mismos pasos.
El objetivo no es llenar el proyecto de listas. Es evitar que tareas importantes dependan de acordarnos de todos los pasos cada vez.
Cuando un proceso está escrito, podemos revisarlo, mejorarlo y repetirlo. Y cuando cambia el proceso, actualizamos la guía.
De la planificación al desarrollo
Esta forma de trabajar encaja con algo que consideramos fundamental en CraftingBits: el desarrollo no es una fase aislada.
Antes de desarrollar hay análisis. Después llega el diseño. Después la arquitectura y el desarrollo. Y antes del lanzamiento hay pruebas, revisión y preparación de la publicación.
La documentación conecta todas esas etapas. El análisis define qué queremos construir. El diseño define cómo queremos que se utilice. La arquitectura define cómo vamos a construirlo. El desarrollo convierte esas decisiones en software. El testing comprueba que lo construido responde a lo que habíamos definido. Y la documentación permite conservar el contexto durante todo el recorrido.
Por eso no consideramos la documentación como un añadido al desarrollo.
Forma parte del proceso de desarrollo.
¿Qué conseguimos con este sistema?
El objetivo final no es tener muchas notas. Es tener menos incertidumbre.
Cuando retomamos un proyecto, no necesitamos reconstruirlo desde cero. Cuando desarrollamos una funcionalidad, sabemos dónde encaja. Cuando una decisión necesita revisarse, podemos consultar por qué se tomó. Cuando llega el momento de publicar, disponemos de un proceso que podemos seguir.
Y cuando empezamos un proyecto nuevo, no partimos completamente de cero: podemos aprovechar los criterios, plantillas y aprendizajes acumulados en proyectos anteriores.
En otras palabras:
Documentamos una vez para no tener que volver a resolver el mismo problema cada vez.
El método continúa
Este artículo es solo la primera parte de una serie en la que vamos a explicar cómo planificamos y estructuramos una aplicación antes y durante su desarrollo.
El recorrido parte de esta base y continúa por:
- La base: documento maestro y vault de Obsidian.
- El documento maestro técnico.
- Las convenciones del proyecto.
- El alcance del producto.
- La arquitectura por capas.
- El flujo de datos, el estado y la inyección de dependencias.
- El modelo de datos.
- La navegación y el mapa de pantallas.
- El sistema de diseño.
- Cómo documentar una pantalla.
- Cómo planificar una funcionalidad compleja.
- Cómo organizar y mover datos.
- La localización desde el diseño.
- Monetización y privacidad.
- Testing.
- Publicación y versionado.
- La deuda técnica.
Cada capítulo parte de las decisiones anteriores.
Porque esa es precisamente la idea de este método:
No construir una aplicación a base de decisiones aisladas, sino avanzar sobre una base que podamos entender, revisar y mantener.
Escribir primero para programar mejor
Programar es una parte importante de construir una aplicación. Pero no es la única.
Una buena arquitectura, una interfaz coherente, un alcance bien definido, un proceso de testing y una publicación controlada empiezan mucho antes de escribir código. Por eso, en nuestros proyectos, intentamos resolver primero las decisiones que van a condicionar todo lo demás. Y dejamos esas decisiones escritas.
Porque dentro de seis meses quizá no recordemos por qué elegimos una determinada solución. Pero si la decisión está documentada, podremos volver a ella.
No documentamos para escribir más. Documentamos para tener que recordar menos.
En el próximo capítulo entraremos en detalle en el documento maestro técnico: qué contiene, cómo lo estructuramos y por qué lo consideramos una de las primeras piezas de cualquier proyecto.
Cargando comentarios…