Engineering Insights
Una habilidad importante para cualquier ingeniero de software es escribir documentos de diseño técnico (TDD), también llamados documentos de diseño de ingeniería (EDD). En este artículo ofrezco algunos consejos para escribir buenos documentos de diseño y los errores que hay que evitar.
Una advertencia: diferentes equipos tendrán diferentes normas y convenciones para el diseño técnico. No existe un estándar en toda la industria para el proceso de diseño, ni podría existir, ya que los diferentes equipos de desarrollo tendrán diferentes necesidades dependiendo de su situación. Lo que voy a describir es una posible respuesta, basada en mi propia experiencia.
Empecemos por lo básico: ¿Qué es un documento de diseño técnico y cómo encaja en el proceso de diseño?
Un documento de diseño técnico describe una solución a un problema técnico determinado. Es una especificación, o «plano de diseño», para un programa o característica de software.
La función principal de un TDD es comunicar a los miembros del equipo los detalles técnicos del trabajo a realizar. Sin embargo, hay un segundo propósito que es igual de importante: el proceso de escribir el TDD le obliga a organizar sus pensamientos y considerar cada aspecto del diseño, asegurándose de que no ha dejado nada fuera.
Los documentos de diseño técnico son a menudo parte de un proceso más amplio que suele tener los siguientes pasos:
- Se definen los requisitos del producto. Estos suelen estar representados por un Documento de Requisitos del Producto (PRD). El PRD especifica lo que el sistema necesita hacer, desde la perspectiva de un usuario o agente externo.
- Se definen los requisitos técnicos. Los requisitos del producto se traducen en requisitos técnicos – lo que el sistema necesita lograr, pero ahora cómo lo hace. El resultado de este paso es un documento de requisitos técnicos (TRD).
- Diseño técnico. Contiene una descripción técnica de la solución a los requisitos expuestos en los pasos anteriores. El TDD es el resultado de este paso.
- Implementación. Esta es la etapa en la que la solución se construye realmente.
- Pruebas. El sistema se prueba contra el PRD y TRD para asegurar que realmente cumple con los requisitos especificados.
Entre cada una de estas etapas suele haber un proceso de revisión para asegurar que no se cometieron errores. Si se detectan errores, malentendidos o ambigüedades, deben corregirse antes de pasar al siguiente paso.
Este proceso es muy variable; el conjunto de pasos que se enumeran aquí cambiará en función de cada caso. Por ejemplo:
- Para las características más pequeñas que no implican mucha complejidad, los pasos 2 y 3 a menudo se combinarán en un solo documento.
- Si la característica implica un gran número de incógnitas o algún nivel de investigación, puede ser necesario construir una implementación de prueba de concepto antes de finalizar el diseño técnico.
Este proceso también ocurre en diferentes escalas y niveles de granularidad. Un PRD / TRD / TDD puede referirse al diseño de todo un sistema o de una sola característica. En la mayoría de los entornos, el proceso también es cíclico: cada ciclo de diseño/implementación se basa en el trabajo del anterior.
La línea divisoria entre TRD y TDD puede ser un poco borrosa a veces. Por ejemplo, supongamos que estamos desarrollando un servidor que se comunica a través de una API RESTful. Si el objetivo es ajustarse a una API ya establecida y documentada, entonces la especificación de la API es parte de los requisitos y debe ser referenciada en el TRD. Si, por el contrario, el objetivo es desarrollar una API completamente nueva, la especificación de la API forma parte del diseño y debe describirse en el TDD. (Sin embargo, el documento de requisitos todavía tiene que especificar lo que la API está tratando de lograr.)
Escribiendo el TDD
Hoy en día, es una práctica común escribir documentos técnicos en un sistema de documentos de colaboración, como Google Docs o Confluence; sin embargo, esto no es un requisito absoluto. Lo importante es que haya una forma de que los miembros de tu equipo puedan hacer comentarios sobre el documento y señalar errores y omisiones.
La mayoría de los TDDs tienen entre una y diez páginas. Aunque no hay un límite máximo para la longitud de un TDD, los documentos muy extensos serán difíciles de editar y de asimilar para los lectores; considere la posibilidad de dividirlo en documentos separados que representen pasos o fases individuales de la implementación.
Los diagramas son útiles; hay una serie de herramientas en línea que puede utilizar para incrustar ilustraciones en el documento, como draw.io o Lucidchart. También puede utilizar herramientas fuera de línea como Inkscape para generar diagramas SVG.
El documento debe ser completo; idealmente, debe ser posible que alguien que no sea el autor de TDD implemente el diseño como está escrito. Por ejemplo, si el diseño especifica una implementación de una API, cada punto final de la API debe ser documentado. Si hay opciones de diseño sutiles, deben ser llamadas a cabo.
Evitar errores comunes de escritura
Probablemente el error más común que encuentro en TDDs es la falta de contexto. Es decir, el autor escribió, en tan pocas palabras como pudo, cómo resolvió el problema; pero no incluyó ninguna información sobre cuál era el problema, por qué necesitaba ser resuelto, o cuáles fueron las consecuencias de elegir esa solución en particular.
También es importante tener en cuenta quién es el probable lector, y qué nivel de comprensión tiene. Si utiliza un término que el lector podría desconocer, no tema añadir una definición del mismo.
No hace falta decir que una buena gramática y ortografía son útiles. Además, evite la tentación de los juegos de palabras o de la ortografía «bonita»; aunque a los programadores, como clase, les gusta jugar con el lenguaje, he visto más de un caso en el que la frivolidad excesiva acabó costando al equipo un esfuerzo perdido debido a los malentendidos. Está bien utilizar el humor de vez en cuando o elegir nombres coloridos y memorables para las funciones y los sistemas, ya que eso ayuda a la gente a recordarlos. Pero no deje que su deseo de mostrar lo inteligente que es se convierta en una distracción.
Hablando de nombres, elíjalos con cuidado; como escribió una vez Mark Twain, «Elija la palabra correcta, no su prima segunda». Hay una tendencia de los ingenieros con un vocabulario pobre a utilizar los mismos términos genéricos una y otra vez para cosas diferentes, lo que lleva a la sobrecarga y la confusión. Por ejemplo, nombrar una clase «Gestor de datos» es vago y no dice nada sobre lo que realmente hace; del mismo modo, un paquete o directorio llamado «utilidades» podría contener prácticamente cualquier cosa. Consulte un tesauro si necesita encontrar una palabra mejor, o mejor, una base de datos de sinónimos especializada como WordNet.
Plantilla de TDD
Cuando se escribe una TDD, puede ser útil empezar con una plantilla estándar. La siguiente es una plantilla que he utilizado en varios proyectos. Tenga en cuenta que esta plantilla debe ser personalizada cuando sea necesario; usted es libre de eliminar las secciones que no se aplican, añadir secciones adicionales, o cambiar el nombre de los títulos, según sea apropiado.