¿Debe un documento de diseño contener una discusión de los pros / contras de un diseño determinado o debe enfocarse en hechos y justificación?

Actualmente estoy en el proceso de actualizar un documento de diseño para que sea correcto y actualizado para futuros desarrolladores.

Actualmente, el documento se centra solo en los hechos, presentando cómo es el diseño. No hay justificación para ninguna decisión presentada. Creo que es importante capturar la lógica para que los desarrolladores sepan por qué algo es así, ya que eso probablemente afectará las decisiones futuras. No es posible para mí agregar una justificación para todas las decisiones de diseño, especialmente aquellas tomadas antes de comenzar a trabajar en el proyecto, pero estoy haciendo lo que puedo en este departamento.

Sin embargo, algunas de las decisiones de diseño son, respetuosamente, decisiones muy malas dados los requisitos del proyecto. Sin embargo, también hay algunos buenos.

Mi pensamiento inicial fue que debería incluir una discusión sobre problemas de diseño y posibles soluciones o soluciones a estos problemas para enfocar la atención de los futuros mantenedores, pero no estoy seguro de si el documento de diseño es un lugar para este tipo de discusión e información. No quiero que una "crítica" del diseño se convierta en "rasgar este diseño uno nuevo" mientras otras personas trabajan en este sistema y actualizan el documento, ya que eso es claramente inapropiado.

Mi gerente apoyaría cualquier decisión, así que depende de mí. Independientemente del enfoque que adopte, el documento producido se versionaría oficialmente y se proporcionaría a los desarrolladores que trabajan en el sistema, generalmente antes de que se encarguen del trabajo de desarrollo. Se espera que un nuevo desarrollador se familiarice con los documentos asociados con un sistema de software dado antes de comenzar el trabajo de desarrollo.

Preguntas:

• En caso de que un documento de diseño se adhiera a hechos en bruto ("este es el diseño") y la justificación ("este es el motivo") o también se debe utilizar para señalar problemas no defectuosos con el diseño que podrían ser problemáticos para futuros desarrolladores?
• Si el documento de diseño no se debe utilizar para capturar esta información, qué tipo de documento debe capturarlo y qué más se debe capturar con una discusión sobre los fundamentos del diseño, las compensaciones y los problemas conocidos (que no son defectos, ya que se rastrean los defectos usando otras herramientas)?

Si los pros y los contras se pueden resumir en una o dos oraciones, entonces está bien incluirlos en un documento de diseño. Cualquier cosa más larga debe ser separada.

Donde trabajo actualmente, generalmente hay un documento separado de "Decisiones de diseño" para rastrear todas las decisiones importantes e importantes. A menudo formateado con un párrafo que describe el problema (como "Algunos archivos deben trasladarse de un servidor a ciertos usuarios al final de cada ciclo de procesamiento, hay muchas maneras de hacer esto ..."), una tabla con columnas " descripción de la solución "(como" mover archivos a través de FTP ")," pros "(como" Fácil de administrar para los usuarios ")," contras "(como" no lo suficientemente seguro para el cumplimiento de ABC-XYZ ") y una conclusión de que explica por qué se eligió una decisión particular (como "FTP no se utilizará porque no podrá cumplir con ciertos requisitos de cumplimiento"). El documento de diseño generalmente solo hace referencia a la decisión elegida,

En caso de que un documento de diseño se adhiera a hechos en bruto ("este es el diseño") y la justificación ("este es el motivo") o también se debe utilizar para señalar problemas no defectuosos con el diseño que podrían ser problemáticos para futuros desarrolladores?

No es "uno u otro".

Nadie lee la documentación en primer lugar. Desnatan, en el mejor de los casos. Por lo tanto, escriba la menor cantidad de documentos posible. Un documento es todo por lo que cualquiera tiene paciencia. Es improbable que se lea un segundo documento "no diseñado" con "otros problemas".

Ventajas de un documento? La gente puede leerlo.

Desventajas de un documento? Pocos. Principalmente se desactualiza.

Ventajas de múltiples documentos? Ninguna.

¿Desventajas de múltiples documentos? Lea el principio DRY y la programación alfabetizada. Múltiples documentos significa múltiples fuentes de errores. Cada documento no está de acuerdo con el otro y no está de acuerdo con el código. Esto es bastante obvio. Este es el camino de la locura.

Evite retorcerse las manos.

Un documento de pros y contras puede extenderse a profundidades indefinidas de discusiones interesantes y molestas.

Si cree que es necesario presentar ventajas y desventajas, manténgalo breve y al grano.

Concéntrate en lo que es.

Mantenga lo que no se reduce a los huesos desnudos.

Si ha realizado puntos de referencia, estudios o explorado alternativas, documente eso. Pero si solo está considerando alternativas, minimícela.

Este no debería ser su historial personal de prueba y tribulación.

• ¿Tuve un problema? ¿Arreglado? Tomó semanas? Realmente luchó? Apenas una anécdota interesante. Está arreglado en el código. Las versiones anteriores, versiones incorrectas, versiones con errores y versiones de bajo rendimiento no importan. Son el blog-forraje en el mejor de los casos.

• ¿Aún tienes un problema? ¿No arreglado? Eso significa que hay alternativas. Documente esto.

Hay 3 hechos importantes en el proceso de toma de decisiones:

• Lo que se intentó y no funcionó (y por qué no funcionó, porque está apuntando a un objetivo en movimiento)
• Que es
• Lo que podría ser (solo esperando que se implemente X ...)

Sin embargo, aparte de "Qué es", todos los demás confundirán al lector y evitarán que asimile el sistema.

Me gusta la idea de capturar los otros 2, aunque son menos interesantes para aprender el sistema, pueden ahorrar tiempo al cambiarlo.

Por lo tanto, me basaría en la idea expuesta @FrustratedWithFormsDesigner, con un giro. En lugar de crear otro documento más, con un ciclo de vida propio, agregaría una sección anexa. Luego, para cada decisión digna de discusión, señalaría la entrada pertinente en el anexo.

Si. Un documento de diseño debe explicar los beneficios, riesgos y supuestos asociados con el diseño que se describe. Un documento de diseño tiene varios propósitos:

1. Anote el diseño para que todos lo entiendan y para que la comprensión de cada persona no se desplace con el tiempo.

2. Comunique el diseño a personas no técnicas que trabajan en el proyecto.

3. Asistir en la programación, asignación de recursos, estimación de costos y otros tipos de planificación.

4. Se convierte en una parte importante de la documentación general del proyecto. Cuando te unes a un proyecto en progreso, o tienes que mantener uno que se ha completado, la vida es mucho más fácil si hay un documento de diseño bien escrito.

5. A menudo es uno de los entregables requeridos por contrato.

(Probablemente hay otros, pero estos son un buen comienzo).

Cada uno de estos propósitos está bien atendido por un documento de diseño que explica claramente por qué se eligió este diseño y cuáles son los riesgos asociados:

1. Es esencial que todos en el equipo sepan cuáles son los riesgos y los beneficios para que puedan trabajar juntos para evitar esos riesgos y aprovechar al máximo los beneficios del diseño.

2. Para los miembros del equipo no técnicos, comprender los riesgos y los beneficios es a menudo más importante que los detalles del diseño en sí.

3. La gestión de riesgos es una de las cosas más importantes que puede hacer un gerente de proyecto para garantizar el éxito, y el primer paso es identificar los riesgos que deben gestionarse. Debería depender de un gerente decidir cómo lidiar con los riesgos, pero es responsabilidad del diseñador señalar los riesgos conocidos del diseño.

4. Incluso cuando un riesgo ya no es un problema, a menudo es útil tenerlo documentado porque puede ayudar a explicar la situación en el momento en que se creó el diseño. Eso puede permitir que un responsable de mantenimiento decida algo como: "Está bien, lo hicieron de esa manera porque ... pero eso ya no es un problema, por lo que puedo reemplazar ese código con una implementación más simple y rápida". Lo mismo ocurre con los beneficios, por supuesto.

5. Si está trabajando en un proyecto para un cliente, entonces es particularmente importante documentar los riesgos y beneficios. Eso le avisa al cliente que las cosas podrían salir mal en ciertas circunstancias, o que solicitar cambios en el diseño podría poner en peligro algunos de los beneficios prometidos.

De la pregunta que deduzco es que está trabajando con un documento de diseño existente para un sistema que ya se ha implementado. En ese caso, muchos de los posibles riesgos ya no son riesgos, por lo que no tiene mucho sentido tratar de documentarlos después del hecho. Sin embargo, ahora tiene la ventaja de la retrospectiva, ya que puede ver las partes del diseño original que no funcionaron tan bien. Creo que usted debería: agregar una sección separada que identifique las áreas problemáticas actuales y proponga soluciones (¡incluidos los riesgos asociados!); o cree un documento separado que haga lo mismo. Esta nueva sección / documento puede evolucionar hacia el documento de diseño para la próxima versión del software.

Aquí hay una entrada de blog sobre cómo escribir documentos de diseño que pueden serle útiles.

Si hubiera razones válidas para evitar soluciones más obvias o estándar, deberían tenerse en cuenta. Ahorrarás a alguien muchos problemas. Sin embargo, una tecnología en particular puede mejorar con el tiempo, por lo que sus razones pueden no ser aplicables. Un futuro desarrollador puede usar su propio juicio.

No sé si hay muchos beneficios en señalar todas las deficiencias. Puede que no sea práctico hacer los cambios u otras prioridades tendrán lugar. Puede solucionar algunos de ellos en un futuro próximo y esto será solo una cosa más para actualizar.

Yo personalmente no lo pondría en el documento de diseño. Un documento de diseño debe describir cómo es, no por qué lo es.

Si cree que hay una buena necesidad de una historia de fondo sobre por qué el diseño es como es, tal vez debería ponerlo en un artículo wiki (o cualquier base de conocimiento que utilice su empresa) para que pueda haber una historia del evolución del diseño. La gente puede ir a leerlo, editarlo y agregar sugerencias. De esa manera, es más una discusión abierta en lugar de una ceja en un documento.

Estoy de acuerdo con usted en poner una justificación en el documento de diseño.

De todas formas,

En el proceso de actualizar un documento de diseño escrito por otra persona, me mantendría humilde y no trataría de adivinar por qué se ha tomado esa decisión.

Entonces,

Insertaría la justificación solo sobre los cambios que se realizan en el diseño durante el mantenimiento.