Communicating elements of software architecture and design#
Software architecture is the result of deliberately designing the relationship between components of a software system. While a general structure of the relationships can be inferred through reading the code itself, the architecture of complex software is often difficult to comprehend accurately and in a reasonable amount of time in this manner. To enable further development of a software, it is critical to document and communicate the design intent and architectural elements for both current developers in the future and new developers joining the project. In practice, the architecture of a software is often communicated through a combination of diagrams that each address a different aspect of the holistic design. This notebook details specific types of diagrams used in the context of communicating software architecture and design. Additionally, tools to produce the diagrams are presented along with additional training resources. Finally, methods for effectively communicating these ideas as part of the project workflow are proposed.
This is intended to be a community resource, so please engage! Create a Discussion in the repository to talk about a particular concept, or open an Issue to let me know where I’ve missed something. Pull requests are welcome, and I will engage with them as quickly as possible. Lastly, feel free to contact me directly at rafael.mudafort@nrel.gov.
This work was supported by the Better Scientific Software Fellowship Program, funded by the Exascale Computing Project (17-SC-20-SC), a collaborative effort of the U.S. Department of Energy (DOE) Office of Science and the National Nuclear Security Administration; and by the National Science Foundation (NSF) under Grant No. 2154495.
Additional outputs of the BSSw Fellowship:
Talk at 2024 National Lab IT Summit S3C Workshop
(slides)
Architecture and Design
Diagrams
Workflows
Reference