Documenting and Communicating Design Decisions

by Steven Fraser and Dennis Mancl
Designing 2025 Workshop – at ICSE 2025

Design is both a human and a technical endeavor. Documenting and communicating design decisions remains challenging. Lightweight graphical models, text, and design-focused unit tests help. However, whether trying to understand the software output of an AI-aided design tool or reusing software components developed by others – documentation, collaboration, and communication remain key to understanding and propagating design decisions.

• Presentation: talk slides (10 slides)
• Workshop Paper: Documenting and Communicating Design Decisions (5 pages)
• official paper: https://doi.org/10.1109/Designing66910.2025.00006

Main conclusions:

• As software development technology has advanced, we need to do more careful design work.
• But as we have moved to lightweight processes, low-level design seems to less valued: developers are jumping to code.
• Will this result in quality problems or increase technical debt?
• Three approaches can help:
  • Development teams should include some low-level design work in each iteration, and this is especially valuable in agile projects. Try to include some design information in the Definition of Done for your project.
  • Use design-focused unit tests as an alternative for modeling notations and text descriptions. “Design-focused” means that the test can help a new developer walk through the code details of key low-level scenarios.
  • Write some focused and short architecture documentation when designing internal features that support architecture: security checks, performance enhancements, and other “architecture stories” – use some lightweight documentation ideas such as “Architecture Haiku” or “Architecture Decision Records (ADRs).”
• The value of doing low-level design documentation and models goes beyond the documentation itself.
  • Thinking: Developers write better code when they do some planning, and a model helps them sketch design alternatives more quickly than writing multiple code prototypes.
  • Teamwork: Some of the best designs are the result of a small team discussing design alternatives at a whiteboard.
  • Learning from others: Reading and reviewing the designs of others is a good way to learn new design ideas, including useful design patterns.
  • Exploring legacy code: When faced with the task of modifying or integrating a large body of unfamiliar code, it is useful to create a simplified software model to record your understanding of the code’s design.