Saber construir un documento de diseño desde cero es una de las habilidades más valoradas en el desarrollo de software. Definir con claridad el problema, los casos de uso, las limitaciones y los costos antes de escribir una sola línea de código marca la diferencia entre un proyecto exitoso y uno que se desborda. A continuación se desglosa el proceso completo para elaborar este documento utilizando un template en Markdown.
¿Cómo iniciar la redacción del documento de diseño?
El punto de partida es tomar el template de documento de diseño disponible en los recursos, copiar su fuente en Markdown y crear un archivo propio, por ejemplo Design Doc.md [00:20]. El formato Markdown permite escribir texto enriquecido que se comparte fácilmente a través de repositorios en Git o plataformas como GitHub [00:50]. Sin embargo, cualquier herramienta funciona: un documento en Word o incluso un bloc de notas sin formato.
Lo primero que se coloca es el título del sistema. En el ejemplo práctico se utiliza "Camera Reviews System" [01:14]. Inmediatamente después viene la sección de problema a resolver, donde se describe el objetivo del proyecto. Aquí se puede copiar y pegar la definición que el cliente compartió previamente, sin necesidad de agregar contenido adicional en esta etapa [01:30].
¿Por qué empezar por los casos de uso y no por el alcance?
Una recomendación clave es comenzar siempre por los casos de uso antes de definir el alcance [02:10]. La razón es directa: los casos de uso determinan exactamente lo que el sistema va a soportar, y a partir de ellos el alcance se define de forma natural.
¿Qué formato deben tener los casos de uso?
Se emplea un lenguaje estandarizado que comienza con "Como [rol], me gustaría poder..." seguido de la acción esperada [02:30]. Algunos ejemplos concretos del proyecto:
- "Como editor, me gustaría poder subir una review de una cámara."
- "Como editor, me gustaría poder subir una review de un lente para las cámaras."
Este formato facilita la comprensión tanto para el equipo técnico como para los stakeholders.
¿Qué son los casos de uso no soportados?
Tan importante como definir lo que se hará es dejar claro lo que no se va a entregar. La sección Out of Scope o "fuera de alcance" documenta estos límites [03:05]. Por ejemplo:
- "Como usuario no registrado, me gustaría poder subir una review de una cámara."
Esto sería técnicamente posible, pero se decide no soportarlo. En cambio, un usuario no registrado sí podrá leer reviews, y eso forma parte de los casos soportados [03:30].
¿Qué más incluye el documento de diseño?
Después de los casos de uso, el documento contiene varias secciones que dan forma técnica al sistema.
¿Cómo se documenta la arquitectura y los modelos de datos?
La sección de arquitectura admite múltiples formatos [04:00]:
- Diseños de entidades.
- Estructuras JSON.
- Definiciones de tablas.
- Diagramas UML y diagramas de secuencia.
Para crear estos diagramas se recomienda utilizar las herramientas disponibles en los recursos del curso [05:40]. Los diagramas aportan una visualización clara de cómo se conectan las piezas del sistema.
¿Por qué las limitaciones deben ser cuantificables?
Las limitaciones conocidas del sistema se documentan en un formato estrictamente cuantificable [04:20]. Esto significa incluir métricas concretas, no descripciones vagas. Dos ejemplos prácticos:
- La llamada al API que permite subir un review no debe exceder los 500 milisegundos de latencia.
- La llamada al API que permite obtener reviews para lectura (un GET) debe tener una latencia menor a 100 milisegundos [04:50].
¿Por qué este nivel de detalle? Porque cuando el sistema crece y la cantidad de usuarios aumenta, las latencias pueden incrementarse. Tener estos valores por escrito permite detectar degradaciones y actuar a tiempo antes de que se conviertan en problemas reales [05:00].
La sección de costos sigue la misma filosofía cuantificable [05:15]. Si el sistema utiliza funciones serverless o bases de datos con cobro por uso, se estima el costo basándose en un tráfico base. Por ejemplo: "contemplando mil usuarios diarios que visitan recurrentemente cada hora". Esta sección es opcional pero altamente recomendada para proyectos grandes, ya que permite predecir cuánto costará operar el sistema.
Ahora es tu turno de completar los casos de uso restantes y dar forma a tu propio documento de diseño. ¿Qué casos de uso agregarías tú? Comparte tu experiencia y las decisiones que tomaste al definir el alcance de tu proyecto.
