Architectural Documentation at NashTech
Working in Software Engineering [1] industry for over 20 years, we have experienced that software architecture design plays an important part. Not only do we need to consider how we organize the software elements, their characteristics, and relationship, but we also need to visualize them in a portable and evolutionary manner to facilitate a consistent understanding among the entire team.
At NashTech, we mainly use 4+1 View Model [2] along with UML for most of projects we work with our customers. During the design and development phases, Software Architecture Documents (SAD) and Detailed Design Documents (DD) normally use these abstraction models to serve for multiple purposes. Despite of the wide areas these models are able to cover, for many years, we still encounter many issues when using them incorrectly:
- The definition and purpose of elements are ambiguous.
- Relationships between elements are missing or ambiguous.
- Notation is not clearly explained or inconsistent (e.g., color, shapes, arrow types, etc.).
- The detail is too precise or excessively vague.
This led us to explore a new approach to software modeling that can help us overcome these issues in an easier way, and we found out C4 Model [3].
C4 Model – The Great Additions
In 2019, we actively did the R&D on C4 Model, and composed materials and slide decks to help our members understand the benefits when using this new modeling approach. With C4 Model, not only were we able to resolve the pain points we encountered for several years, but it also created a set of maps to help the involved audiences jump around at varying levels of detail.
From 2020, we rolled out this model application for a few customer projects. So far, C4 Model is a part of our software modeling approach in software engineering phases including assessment, planning, development, etc. One of the most interesting parts of the application is the way we combine C4 Model along with 4+1 View Model to leverage their advantages.
Improving Communication Culture
Effective communication is a key factor in the success of your product.
– Jesse James Garrett –
Approximately 80% of project success comes from the effective communication. And good documentation and visualization play a crucial role in facilitating it. Along with the hands-on application in projects, we also spread out this knowledge to our members through the internal training-program. There were 3 courses had been delivered until 2023. The key takeaways from this training will help Nashers:
- Gain proficiency in modern software development practices to effectively design and implement software components.
- Develop confidence in articulating and communicating detailed software designs to customers with clarity and precision by completing the assignment.
Reaching out for more information with our upcoming article on Diagram as Code with C4 Model – Why Not
References:
[1]: Software Engineering at NashTech – NashTech Insights (nashtechglobal.com)
[2]: Architectural Blueprints – The “4+1” View Model of Software Architecture (ubc.ca)
