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

Si los pros y los contras se pueden resumir en una oración o dos, entonces está bien ponerlos en un documento de diseño. Cualquier cosa más larga debería estar separada.

Donde trabajo actualmente, generalmente hay un documento separado de "Decisiones de diseño" para rastrear todas las decisiones importantes e importantes. A menudo, está formateado con un párrafo que describe el problema (por ejemplo, "Algunos archivos deben trasladarse de un servidor a ciertos usuarios al final de cada ciclo de procesamiento, hay muchas formas de hacerlo ..."), una tabla con columnas " descripción de la solución "(como" mover archivos a través de FTP ")," pros "(como" Fácil de administrar por los usuarios ")," contras "(como" no es lo suficientemente seguro como para cumplir con ABC-XYZ ") y una conclusión que explica por qué se eligió una decisión particular (por ejemplo, "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, y puede recomendar a los lectores que lean el documento de decisión para obtener una descripción completa de otras opciones.

  

Si un documento de diseño se adhiere a los datos sin procesar ("este es el diseño") y la lógica ("aquí es por qué este es el diseño") o si también se debe usar para señalar problemas no defectuosos con el diseño que podría ¿Ser problemático para futuros desarrolladores?

No es "o-o".

En primer lugar, nadie lee la documentación. Skim - en el mejor de los casos. Por lo tanto, escribe la menor cantidad de documentos posible. Un documento es todo lo que cualquiera tiene paciencia para. Es poco probable que se lea un segundo documento "no diseñado" con "otros problemas".

¿Ventajas de un documento? La gente podría leerlo.

¿Desventajas de un documento? Pocos. Sobre todo se queda desactualizado.

¿Ventajas de múltiples documentos? Ninguno.

¿Desventajas de múltiples documentos? Por favor lea sobre 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.

Evita el retorcimiento de manos.

Un documento de pros y contras puede extenderse a las profundidades indefinidas de las discusiones sobre "qué pasaría si" y las molestias atractivas.

Si cree que es necesario presentar ventajas y desventajas, sea breve y conciso.

Enfócate en lo que es.

Mantén lo que no está en los huesos desnudos.

Si ha realizado evaluaciones comparativas, estudios o explorado alternativas, documéntelo. Pero si solo estás considerando alternativas, minimízalo.

Este no debe ser su historial personal de prueba y tribulación.

• ¿Ha tenido algún problema? ¿Arreglado? Tomó semanas? Realmente luchado? Apenas una anécdota interesante. Se fija en el código. Las versiones anteriores, las versiones incorrectas, las versiones con errores y las versiones de bajo rendimiento no importan. Son, en el mejor de los casos, contenido para blogs.

• ¿Aún tienes un problema? ¿No arreglado? Eso significa que hay alternativas. Documentar 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ás apuntando a un objetivo móvil)
• ¿Qué es?
• Qué podría ser (solo esperando que X se implemente ...)

Sin embargo, aparte de "Qué es", todos los demás confundirán al lector e impedirán que se trabe en el sistema.

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

Por lo tanto, me gustaría desarrollar la idea expuesta @FrustratedWithFormsDesigner, con un toque. En lugar de crear otro documento, con un ciclo de vida propio, agregaría una sección de anexo. Luego, para cada decisión digna de discusión, señalaré la entrada correspondiente en el anexo.

Sí. Un documento de diseño debe explicar los beneficios, los riesgos y las suposiciones asociadas 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 desvíe con el tiempo.

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

3. Ayude 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 se une a un proyecto en curso, o tiene 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. Es a menudo uno de los entregables requeridos por contrato.

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

Cada uno de estos propósitos está bien servido 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 beneficios para que puedan trabajar juntos para evitar esos riesgos y hacer un mejor uso de los beneficios del diseño.

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

3. La administració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 administrarse. Debería ser responsabilidad 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 documentarlo porque puede ayudar a explicar la situación en el momento en que se creó el diseño. Eso puede permitir que un mantenedor decida algo como: "Está bien, lo hicieron así entonces porque ... pero eso ya no es un problema, así 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, es particularmente importante documentar los riesgos y beneficios. Eso avisa al cliente de 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 se deduce que está trabajando con un documento de diseño existente para un sistema que ya se ha implementado. En ese caso, muchos de los riesgos posibles 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 debería: agregar una sección separada que identifique las áreas problemáticas actuales y proponga soluciones (¡incluidos los riesgos asociados!); o crear 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 puede encontrar útil.

Si hubiera razones válidas para evitar soluciones más obvias o estándar, se deben tener en cuenta. Ahorrarás a alguien un montón de problemas. Sin embargo, una tecnología en particular puede mejorar con el tiempo, por lo que es posible que sus razones no sean aplicables. Un futuro desarrollador puede usar su propio juicio.

No sé si hay mucho beneficio en señalar todos los inconvenientes. Puede que no sea práctico hacer los cambios u otras prioridades se llevarán a cabo. Puede arreglar 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é es.

Si cree que hay una buena necesidad de contar con una historia de fondo de por qué el diseño es como es, tal vez debería incluirlo en un artículo de wiki (o cualquier base de conocimientos que use su compañía) para que pueda haber una Historia de la evolución del diseño. La gente puede leerlo, editarlo y agregar sugerencias. De esa manera es más una discusión abierta en lugar de una paliza en un documento.

Estoy de acuerdo con usted acerca de incluir el fundamento en el documento de diseño.

De todos modos,

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

Entonces,

Insertaré las razones solo sobre los cambios que se realizan en el diseño durante el mantenimiento.