Cómo crear documentos de diseño de software

Imagínate esto: inicias un largo viaje por carretera, pero, en lugar de usar un mapa, empiezas a conducir hacia la dirección general de tu destino. Claro, puede que al final lo consigas. O puedes acabar totalmente perdido. En cualquier caso, has perdido un tiempo valioso que podrías haberte ahorrado si hubieras utilizado un mapa.

Del mismo modo, antes de sumergirte en un proyecto y comenzar a programar, es importante que tú y las otras partes involucradas sepan exactamente hacia dónde se dirigen. Necesitan un plan, en este caso, un documento de diseño de software. Al igual que un mapa, un documento de diseño de software (SDD, por sus siglas en inglés) puede ayudarlos a ti y a tu equipo a mantener el rumbo desde el comienzo de un proyecto hasta las últimas líneas de código. 

Si eres nuevo en los documentos de diseño de software, no te preocupes. Esta publicación abarca todo, desde los conceptos básicos hasta las prácticas recomendadas y consejos pro. E incluso si eres un profesional con experiencia, nunca está de más repasar tus conocimientos sobre SDD, ¿verdad?

¿Qué son los documentos de diseño de software?

Un documento de diseño de software, a veces denominado "especificación de diseño de software", es un plan detallado para desarrollar una pieza de software. Debe describir la funcionalidad del software terminado (especificaciones) y los planes de tu equipo para desarrollarlo (cronograma, objetivos, etc.). 

Tanto si eres un contratista independiente o un gerente de proyectos en una gran empresa, hay algo indudable: para cualquier proyecto que lleve más de un mes, deberías crear un SDD antes de comenzar a programar. Es tentador saltearse los pasos de planificación y dedicarse directamente a la programación. Después de todo, los documentos de diseño de software no son exactamente divertidos. Pero confía en nosotros: tomarte el tiempo para crear un buen SDD te ahorrará dolores de cabeza en el futuro. 

Los documentos de diseño de software desglosan casi todos los aspectos de un proyecto de desarrollo de software: ¿qué problema solucionará el software? ¿Cómo será el producto final? ¿Cómo funciona la arquitectura interna? (Hablaremos de los detalles de lo que debes incluir en tu SDD más adelante). 

¿Por qué son importantes los SDD?

Si eres un desarrollador, tal vez te ha pasado esto: escribiste miles de líneas de código y luego te diste cuenta de que tú y el cliente tenían visiones completamente diferentes del proyecto. Eso son miles de líneas de código (y quién sabe cuántas horas de trabajo) que podrías tener que desechar.

Al crear un documento de diseño de software, tu equipo de ingeniería y las otras partes interesadas pueden establecer expectativas precisas para el proyecto antes de comenzar a programar. Aunque no hay una forma segura de evitar la reelaboración de los elementos del proyecto, un SDD es un buen punto de partida. 

Los SDD también ayudan a agilizar el proceso de codificación. Para crear uno, debes pensar en toda la arquitectura de tu sistema antes de escribir cualquier código. Esto te permite anticipar cualquier inconveniente u obstáculo y planificar en torno a ellos. A medida que los distintos miembros del equipo trabajan en la creación de sus respectivas partes del software, existe un documento centralizado que describe las funciones, las dependencias y otra información útil. 

Qué incluir en los documentos de diseño de software

Ahora que tenemos una visión general del camino, es hora de ponernos puntillosos. ¿Cómo se ve realmente un documento de diseño de software? 

Aunque cada documento será único, la estructura general de los SDD es bastante similar en todos los proyectos. Al crear el tuyo, asegúrate de incluir estos elementos.

Título, autores y revisores

Puede parecer obvio, pero lo hemos incluido por las dudas. Te sorprenderían las cosas que la gente olvida. Al principio de tu SDD, recuerda incluir el título del proyecto, los autores (del documento, no del software) y los revisores (por lo general, partes involucradas que no son de ingeniería).  

Descripción funcional

Con esta sección, intentas responder una pregunta simple: ¿qué hace el software? Por supuesto, para responderla a fondo, tendrás que profundizar un poco más. En la descripción funcional, deberías cubrir el manejo de errores, los procedimientos de inicio único, las limitaciones de los usuarios y otros detalles similares. 

Interfaz de usuario

Es muy probable que tu proyecto de codificación sea una aplicación, lo que significa que tendrá una interfaz de usuario (si el proyecto es una biblioteca o algo similar, no habrá interfaz). Mientras los clientes, diseñadores de UX y programadores analizan y planifican la interfaz de usuario, es fácil que haya malentendidos. Si el cliente no comunica adecuadamente su idea, tus equipos pueden construir una interfaz de usuario cuyo diseño sea rechazado. 

La buena noticia es que estos contratiempos son, en su mayor parte, totalmente evitables. Solo necesitas hablar sobre algunos temas con el cliente antes de iniciar la etapa de desarrollo. ¿Cambian ciertos elementos de la interfaz (animaciones)? ¿Qué elementos son botones? ¿A cuántas pantallas únicas puede navegar el usuario? Y, por supuesto, ¿qué aspecto tiene todo esto?

Y hay más buenas noticias: ¡los wireframes pueden ayudarte a responder todas esas preguntas! Cuando el cliente explique su idea de la interfaz de usuario (quizás mediante bocetos en bruto), tus equipos deberían crear wireframes.

Una vez que el cliente los apruebe, inclúyelos en la sección de interfaz de usuario del documento de diseño de software.

Objetivos e hitos

En lugar de abordar el proyecto como un proceso único y prolongado, puede que te resulte útil dividirlo en partes más manejables (esto aplica para el cronograma del proyecto y el código en sí). En el nivel más macro, tienes un objetivo general: ¿qué problema aborda tu software? ¿Quién lo usará?

Debajo de eso, tienes una serie de hitos. Los hitos son esencialmente puntos de control para que las partes involucradas sepan cuándo se completarán ciertos aspectos del proyecto. Son tanto de uso interno como externo: ayudan a mantener el rumbo de tu equipo de ingenieros y también puedes utilizarlos para mostrarle al cliente los pasos cuantificables que tus equipos están dando para terminar el proyecto. 

priorización

A medida que empieces a dividir el proyecto en funciones más pequeñas e historias de usuario, es útil clasificarlas según la prioridad. Para ello, coloca cada función en una matriz de priorización: un gráfico de cuatro cuadrantes que te ayuda a ordenar las funciones según la urgencia y el impacto. El eje horizontal va de urgencia baja a alta, y el eje vertical va de impacto bajo a alto.

Según el cuadrante en el que caiga cada función, decide si deseas incluirla en tu producto mínimo viable (MVP, por sus siglas en inglés). Las funciones del cuadrante superior derecho (urgencia alta, impacto alto) deben incluirse en el MVP. Para las funciones de los cuadrantes de la parte inferior derecha (urgencia alta, impacto bajo) y de la parte superior izquierda (urgencia baja, impacto alto), usa tu criterio para decidir si formarán parte del MVP. Las funciones del cuadrante inferior izquierdo (urgencia baja, impacto bajo) no deben incluirse. 

Soluciones actuales y propuestas

Vas a crear un software para resolver un problema, pero puede que el tuyo no sea el primer intento de solución. Es muy probable que exista una solución actual (o existente), por lo que deberías describirla en tu SDD. 

No necesitas entrar en los pequeños detalles, pero al menos deberías escribir una historia de usuario: ¿cómo interactúa un usuario con esa solución? ¿Cómo se manejan los datos?

A continuación, podrás incluir una sección que describa la solución propuesta. Si existe una solución existente, ¿por qué se necesita la solución propuesta? Ahora es tu oportunidad para justificar el proyecto. Es importante explicarlo con el mayor detalle técnico posible, ya que, después de leer esta sección, otro ingeniero debería ser capaz de crear la solución propuesta, o algo similar, sin ningún conocimiento previo del proyecto.

Línea del tiempo

La sección de hitos de tu SDD debería proporcionar un plazo general para las partes involucradas que no son de ingeniería. Esta sección es mucho más detallada y, principalmente, beneficia a los equipos de ingeniería. En tu cronograma, incluye tareas y plazos específicos, así como los equipos o individuos a los que están asignadas. 

Consejos pro para crear tus documentos de diseño de software

Que crees un documento de diseño de software e incluyas cada una de las secciones mencionadas anteriormente no significa que será eficaz. Es un comienzo, claro, pero para aprovechar al máximo tus SDD, ten en cuenta estos consejos.

Usa lenguaje sencillo

Cuando se trata de documentos de diseño de software, la claridad es clave. No hay necesidad de un lenguaje florido ni de oraciones largas y complejas. Usa frases cortas y precisas. Cuando corresponda, incluye viñetas o listas numeradas.

Incluye elementos visuales

Vuelve a pensar en la sección de interfaz de usuario. Con los wireframes, puedes comunicar con precisión un diseño que sería casi imposible de describir por escrito. También es posible que los diagramas de clases, los cronogramas y otros gráficos sean igualmente útiles en otras partes de tu SDD. 

Recibe comentarios con antelación

El primer borrador de un SDD no necesariamente debe ser el último; debería ser uno de muchos. Cuando crees un documento de diseño de software para tu proyecto, envíaselo al cliente y a las otras partes involucradas. Es posible que detecten secciones que necesitan ampliarse o partes que no estén claras y no te hayas dado cuenta. Una vez que hayas recibido sus comentarios, revisa las veces que sean necesarias.

Actualiza tu SDD

Una vez que hayas escrito tu documento de diseño de software y tengas la aprobación de las partes interesadas, no lo guardes en un cajón olvidado (o lo que sea que fuere el equivalente digital). A medida que el proyecto avanza, los miembros del equipo deberían usar el SDD como referencia constantemente. Si hay algún retraso, actualiza el cronograma. Al tratar a un SDD como un documento dinámico, este se convertirá en una fuente única de información invaluable.