Escribiendo un documento de arquitectura

El bueno de Federico Jack me envió este enlace, que me parece estupendo para analizar, sobre las características que debe tener un documento de arquitectura de un sistema:

http://stal.blogspot.com/2006/03/what-should-be-in-architecture.html

En su blog, Michael, de Bavaria, escribe sobre varios temas, entre ellos, la arquitectura de software. Repasemos algunos de los puntos y detalles que menciona (me hubiera gustado tener esta lista desde hace tiempo), con modificaciones y agregados personales míos:

  • Describa la arquitectura de arriba a abajo: presente la visión general primero, y luego vaya tratando cada uno de los puntos más en detalle, ya sea de diseño o implementación.
  • Agregue un glosario: algo que podemos olvidar, pero muchos términos serán desconocidos o confusos, o peor, serán mal entendidos por alguien que tenga un contexto distinto al nuestro.
  • Cada vez que introduzca un término que se conoce por una sigla, no presuma que todo el mundo sabe qué significa: coloque la sigla, y las palabras completas que describe.
  • Que no exceda las 50 páginas: si es más extenso, no será leído en detalle. Recuerde que muchas personas que lo lean serán personas con cargos de responsabilidad, que pueden no tener todo el tiempo del mundo para leer su obra maestra.
  • Todos los documentos de arquitectura que entregue, deben usar la misma plantilla: distintos tipos de letras y formatos entre documentos, confunden a los lectores. La estructura debe ser la misma para todos: si usa una tabla de contenido, un resumen, una conclusión en un documento, deberá usarse en todos.
  • Si usa diagramas, úselos consistentemente. Si para explicar un concepto usa UML, cuando tenga que exponer un concepto similar siga con ese tipo de diagrama. Y use los mismos elementos: si en un diagrama UML usó algunos estereotipos, siga usándolos cuando sean necesarios, con las mismas notaciones e íconos.
  • Agregue referencias a otros documentos que pueden ser importantes para entender algún concepto o explicitar una fuente consultada.
  • Explique siempre cómo la arquitectura descripta cumple con los requerimientos que se quieren alcanzar. Debe haber una trazabilidad desde los requerimientos a la arquitectura definida.
  • Coloque al comienzo un resumen: sea gentil con el lector, prepárelo para lo que va a encontrar. Por lo mismo, si un documento lleva varias páginas y abarca varios temas, incluya un índice. Si es necesario, describa los prerrequisitos que debe cumplir de antemano un lector que quiera entender el documento.
  • Si tiene que entregar varios documentos, estructure el conjunto como un árbol. El documento raíz describirá la arquitectura desde un punto de vista alto, estratégico. Desde ahí, los documentos nodos hijo irán explicando los subsistemas relevantes, y los elementos que atraviesan los demás, como seguridad y escalabilidad.
  • Describa la especificación de la arquitectura, y cómo esa especificación puede ponerse a prueba, como cuando programamos “unit tests”.
  • Compruebe que el documento acompañe, describa la implementación actual del sistema. Sino, será una pérdida de tiempo para quien lo lee, y hasta puede provocar errores, al tomar decisiones sobre una especificación que no corresponda con el producto actual.
  • Describa las decisiones de diseño en detalle, que no quede solamente la descripción de la decisión tomada, debe quedar claro que hubo una decisión en ese punto, por ejemplo, mencionando alguna alternativa.
  • Relacionado con lo anterior, no sólo describa el “cómo” sino también el “por qué”. Es importante que otra persona entienda las razones que llevaron a tomar un camino en el diseño.
  • Si se refiere a algún software entregado con el documento, o a utilizar, incluya la versión del mismo: no presuma que será evidente cuál es la versión a la que se refiere.
  • Agregue diagramas y dibujos para explicar las decisiones de diseño tomadas. Los diagramas llevan tiempo de armado, pero el resultado vale la pena.
  • Explique los diagramas: una imagen vale más que mil palabras, pero también hay que entenderla.
  • Pida que otras personas revisen el documento. Uno siempre escribe desde su propio contexto, y tal vez lo que a nosotros nos parece claro, para otro no lo sea. Trate que sea una persona que no esté en el mismo proyecto, para probar si el documento es entendible para alguien que no está al tanto de los conceptos tratados.
  • Use un sistema de control de versiones: no pierda la historia del documento.
  • Escriba los nombres del autor o autores, y forma de contactarlos, en caso de ser necesario. Incluya fecha y hora de versión.
  • No tiene que escribir todo el documento desde el principio al fin: vaya utilizando otros documentos menores que haya producido durante el proceso de discusión y diseño de arquitectura, pero asegúrese su consistencia. Recuerde: ¿cómo se come uno un elefante? Bocado a bocado.
  • No necesita explicar el sentido de cada patrón usado: remita su descripción a la literatura especializada.
  • Como en todo documento, sea consistente en el uso de los tiempos verbales, el uso o no de la forma pasiva, la forma de usar pronombres, si “dialoga” o no con el lector, el uso de la primera o tercera persona.

¿Se les ocurre algo más? ¿Comentarios, correciones, críticas?

Nos leemos!

Angel “Java” Lopez
http://www.ajlopez.com/

This entry was posted in 1392. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>