bycuriosity

Software Design Documents

Software Design Document (SSD)

El diseño de software es un proceso en el cual los requisitos de software son trasladados a una representación de componentes de software, interfaces e información necesaria para la fase de implementación.

El SSD muestra como se estructurará el sistema para satisfacer los requisitos. Es la referencia principal para desarrollar el código y por lo tanto debe contener toda la información requerido por un programador para escribir el software.

El objetivo del documento de diseño es convencer al lector y al autor que el diseño propuesto es optimo dada la situación.

El SSD se realiza en dos fases. La primera es el preliminary design (diseño preliminar), en la cual la arquitectura del sistema y la arquitectura de los datos es definida de forma general. En la segunda fase, el detailed design (diseño detallado), se definen y desarrollan estructura de datos y algoritmos más detallados para la arquitectura propuesta.

But a perfect doc is written such that the reader is never surprised. The reader should find that every sentence flows obviously from the previous ones. They should finish your doc and think “well this was entirely straightforward, why did we even need to have this meeting?”.

But a good doc will lay out the problem and mental models in a way that the solution that took weeks of hard thought to invent will be clear to the reader by the time the doc presents it.

The goal of your doc is to take their minds from their current state to a new state in which they believe your design is a good one.

Once you’ve got the information organized and laid out properly, the next step is to edit for length. Remove every word that can be removed. Do this because your readers’ attention is a scarce resource.

Plantilla de IEEE

  1. Introducción
    1. Propósito
      • Identificar el propósito y la audiencia el SDD
    2. Alcance
      • Descripción y alance del software, se explican los objetivos y beneficios del proyecto
    3. Resumen
      • Resumen del documento y su organización
    4. Material de referencia
    5. Definiciones y acrónimos
  2. Resumen del sistema
    • Proporciona una descripción general de la funcionalidad, contexto y diseño del proyecto. Probé cualquier antecedente si es necesario.
  3. Arquitectura del sistema
    1. Diseño arquitectónico
      • Desarrolla la estructura modular de un programa y explica las relaciones entre los módulos para lograr la funcionalidad completa del sistema. El propósito principal es obtener un entendimiento general de cómo y por qué el sistema fue descompuesto y como las partes individuales trabajan juntas. Se puede proporcionar un diagrama que muestre los sub-sistemas principales, los repositorios de datos y sus interconexiones.
    2. Descripción de la descomposición
      • Proporciona una descomposición de los sub-sistemas. Agrega el modelo del sub-sistema, diagrama de objetos, diagramas de secuencia y especificaciones de la interfaz.
    3. Razones del diseño (Design Rational)
      • Discute las razones de la arquitectura propuesta, incluye issues y trade/offs que se consideraron. Discute otras arquitecturas que fueron consideradas y el por qué no fueron usadas.
  4. Diseño de los datos
    1. Descripción de los datos
      • Explica como la información de dominio del sistema es transformada en estructuras de datos. Describe como las entidades del sistema son almacenadas, procesadas y organizadas.
    2. Diccionario de datos
      • Alfabéticamente lista las entidades del sistema o datos principales junto con sus tipos y descripciones. Lista los objetos y sus atributos, métodos y sus parámetros.
  5. Diseño de componentes
    • En esta sección se realiza una vista detallada a lo que realiza cada componente en una forma más sistemática. Resume cada objeto listado en la sección 3.2.
  6. Diseño de la interfaz de usuario
    1. Resumen de la interfaz de usuario
      • Describe la funcionalidad del sistema desde la perspectiva del usuario. Explica como el usuario será capaz de usar el sistema para completar todas funcionalidades esperadas y la información de retroalimentación que será mostrada para el usuario.
    2. Prototipos
    3. Objetos de la pantalla y acciones
      • Discute los prototipos y acciones asociadas.
  7. Matriz de requisitos
    • Proporciona una matriz cruce los componentes y estructura de datos con los requisitos de tu documento SRS.
  8. Apéndices

Plantilla de blog ‘Write design docs like amazon’

  1. Problem statement
    • Present an abstract of your document that clearly and succinctly defines your problem, summarizes your solution, and states your goal.
  2. Glossary
  3. Use Cases
    • Define los casos de uso en términos de impacto o valor del negocio no resultados técnicos. Ten una lista representativa de ejemplos pero que no sean exhaustivos. Trabaja hacia atrás y muestra la perspectiva del cliente.
  4. Breaking changes
    • Especifica si tu diseño rompe clientes, servicios o algo más.
  5. Success criteria
    • ¿Qué medirás y cuantificarás para demostrar que has resuelto el problema con éxito? Utiliza valores relativos y absolutos.
    • Ejemplos:
      • Performance – Time-to-first-byte (TTFB) will improve 4x, from 200ms to 50ms.
      • Cost – We’ll reduce our DataDog bill by $12,000 each month, from $30,000 to $18,000.
      • Adoption By Q2, 25% of our users (4,250) will be using this new version, based on NPM downloads.
      • Stability Our session error percentage will drop from 3% to 1%, eliminating crashes in 2,000 sessions a month.
  6. Proposed design
    • Céntrate en ideas, conceptos y principios que sean verdaderos en cuanto a su orientación, independientemente de su implementación. Debe haber características clave que se logren a través del diseño técnico que se describe a continuación.
  7. Technical design
    • Aquí se discute como alcanzar la solución. Describe el camino feliz y casos de uso bien soportados. Si edge-cases o errores impactan el diseño inclúyelo.
  8. Componentes
  9. Dependencies
  10. Monitoring
    • De manera similar a las métricas de éxito orientadas al cliente o al negocio mencionadas anteriormente, ¿cómo realizarás el seguimiento de las métricas técnicas para la salud y estabilidad de tu solución?
  11. New APIs or behaviors
  12. Pros & Cons
    • Demuestre que ha considerado de manera pragmática el impacto de adoptar su solución, así como el de no adoptarla.
      • ¿Existe algún coste de desarrollo que pueda restar recursos o retrasar otras iniciativas?
      • ¿Es fácil o difícil mantener esta solución? ¿Afectará esto a la plantilla?
      • ¿Esta solución introduce complejidad que afecta a la carga operativa o de guardia?
      • ¿Se trata de 1-way or 2-way door decision?
  13. Major risk & mitigations
  14. Security
    • Los buenos diseños también van acompañados de una revisión de seguridad independiente.
      • ¿Cambia la superficie expuesta de nuestros sistemas?
      • ¿Se recopilan o almacenan nuevos datos? ¿Qué tipo de datos? ¿Dónde se almacenan? ¿Qué ocurre si se exponen?
      • ¿El diseño es seguro por defecto? ¿O se requieren medidas adicionales para mejorar la postura de seguridad?
  15. Scope
    • Considera cuál es el mínimo trabajo posible para resolver los casos de uso anteriores, sin tener que “hervir el océano”.
  16. Out of scope
    • Una vez definido un conjunto mínimo de tareas, aquí se puede enumerar la entrega incremental. Aquí es donde se pueden «prever» posibles necesidades, pero sin bloquear la solución para ellas.
  17. Alternatives considered
    • A estas alturas, ya deberías tener una propuesta bien redactada para tu solución. Pero «no hacer nada» es una opción que hay que tener en cuenta.
    • Del mismo modo, incluye sistemas o soluciones alternativas que sean similares, pero que se queden cortas lo suficiente como para justificar el esfuerzo de redactar esta maldita propuesta y construir la maldita cosa.
  18. FAQ
  19. Open questions & feedback
  20. Appendix

Notas

Hay muchas cosas que comparten ambas plantillas aunque siento una diferencia entre ambas, la de IEEE parece que esta enfocada a sistemas que serán diseñados por primera vez y requieren todo un documento de especificación de requisitos, aún no se consideran algunos puntos como quien usara el sistema, los clientes, que métricas se obtendrán para comprobar si el desarrollo fue exitoso. Por otro lado la plantilla inspirada en la experiencia de amazon se siente más real y enfocada a desarrollar cosas nuevas que deben ser incluidas con algo ya existente y que esta siendo usado por alguien, las APIs, los clientes, los posibles errores, las métricas y algunos detalles extras me hacen ver que piensan en como será realmente usado y validado Uno se siente abstracto y el otro más concreto.

Muchos de los consejos para escribir un buen documento de diseño también son consejos para escribir bueno ensayos, en general son consejos para escribir y pensar claramente.

Documentos claros y precisos, con algo importante que decir. Me recuerda a lo que decía Schopenhauer en su libro del arte de pensar, en el que critica a los escritores comerciales que solo escriben por dinero. Ellos tratan de extender lo más que pueden sus ideas, sus escritos no son claros ni precisos pues no tienen nada que decir, solo lo hacen por el dinero.