The purpose of every diagram is to visually convey important information with a minimum amount of associated explanation. To that end, a diagram will contain a legend that explains what the boxes and lines and other symbols mean. When standard diagrams are used, such as
|Name UML or ||Term||Name SysML diagrams, it is still helpful to include a notation summary (perhaps as a reference page) for readers and reviewers who are not as familiar with the notations. Also, when a diagram contains acronyms, it’s helpful to include acronym definitions in the legend, even if they are repeated in the glossary.|
The SEI template makes no mention of diagram legends.
4.13 Architecture Frameworks (Views and Viewpoints)
As noted earlier, an architecture description addresses numerous stakeholder concerns, and many architecture thought leaders have thought about how to organize their thoughts—and architecture descriptions—from different viewpoints. As a result, there are now many architecture frameworks for architects to draw upon, such as the Department of Defense Architecture Framework (
|NameDoDAF), The British Ministry of Defense Architecture Framework (||Term||NameMoDAF), The Open Group Architecture Framework (||Term||NameTOGAF), Reference Architecture for Space Data Systems (||Term||NameRASDS), Reference Model of Open Distributed Processing (RM-ODP), and Zachman |
Krutchen’s “4+1” view model calls for a logical architecture (what the system provides in terms of services), a process architecture (a set of processes distributed across a set of hardware resources), a development architecture (software module organization on the software development environment), a physical architecture (different physical configurations for development, testing, and deployment), and scenarios (instances of use cases that show the four views working together seamlessly).
The DoDAF 2. 0
4.14 Heritage Analysis
Most software built for today's missions involve significant "heritage" or "legacy" from an earlier mission, whether in architecture, design, or code or reuse of product line software. Such inheritance can be a smart move for projects, but it is critical to understand the differences between the new mission and the earlier mission and the costs and risks of reuse.
The well-known story of Ariane 5 Flight 501
Fortunately, NASA’s Earth Science Data Systems Software Reuse Working Group has formalized such evaluations in a document “Reuse Readiness Levels (RRLs)” [Marshall 2010]
Surprisingly, the SEI template makes no mention of “heritage software” or “legacy software”. Although the word “reuse” appears in the title of Section 2.3 (Product Line Reuse Considerations), that section is not about reusing existing software, but about making software reusable to support a product line version. The decision to reuse software should be documented in Section 2.2.1 (Architectural Approaches) and the analysis substantiating that decision should be documented in Section 2.2.2 (Analysis Results).
Some questions to address in a heritage analysis:
See SWE-027 for a broader discussion on heritage or reused software and additional items to consider.
4.15 Assumptions and Limitations
Architects recognize that the systems they are architecting might well provide heritage for a future project. As such, it is valuable to document any assumptions underlying an architecture and any inherent limitations. Admittedly, this can be difficult because many assumptions are unconsciously made based on mission specifics, resulting in hidden limitations of the system's suitability for future missions.
The SEI template makes passing reference to “assumptions” as externally visible properties, so the rather clear concept of “assumption” gets lost in the common meaning of “properties”. Some treatment of “assumptions” should appear in Section 2.2 (Solution Background) so that known assumptions will get passed along to future architects who need to extend the architecture or apply it in a new context.
Assumption: Disturbances that the attitude control system must correct for will not exceed 1.5 Newton.
4.16 Architectural Principles, Patterns, Invariants, and Rules
Although a system to be built may be large, its architecture can often be described compactly, and more readily understood, in terms of principles that shape the design and architectural patterns that are applied consistently. An architectural pattern, applied uniformly, greatly aids understanding by software designers, developers and reviewers.
While it is extremely useful to document an architecture in terms of principles and patterns, there's no guarantee that downstream designers and developers will consistently adhere to them, meaning that the built system may not possess all the characteristics promised by the architect. As such, it's often important to provide some means for checking adherence to the principles and patterns.
Section 2.2.1 (Architectural Approaches) of the SEI template includes the use of architectural styles or design patterns, and Section 3.1.3 includes patterns.
4.17 Fault Management
Fault management has often been a source of problems in the integration and testing phase of flight systems, so it should be given suitable attention in architecture descriptions. Fault management encompasses topics that often appear under a variety of names such as fault protection; failure modes and effects analysis (FMEA); fault detection, isolation, and recovery (FDIR); fault detection, diagnostics and response (FDDR ); fault detection, notification and response (FDNR), integrated vehicle health management (IVHM ); integrated systems health management (ISHM); caution & warning; and aborts. At a minimum, fault management is to be examined in terms of its interactions with the nominal control system and its behavior in the face of concurrent faults and responses. For more information, see the Fault Management Community of Practice on NASA Engineering Network (NEN)
The SEI template makes passing mention of “fault handling” in a general paragraph on software architecture and, once again, lumps an important issue under “externally visible properties”. Architects should make sure that fault management is appropriately addressed (and emphasized) in views of behavior.
Systems often have some easy-to-meet requirements, and often build upon mature heritage designs and software. For example, consider a mission that has modest uplink and downlink data rates relative to the proven capabilities of a heritage design that they are reusing and adapting. In that context, downlink data handling might be considered a "non-concern." It is reasonable, and even desirable, to treat these areas of non-concern lightly in the architecture description. However, good practice indicates that such areas first be identified as non-concerns, with good explanations as to why they are non-concerns. (See 4.14 Heritage Analysis.)
Non-concerns can be addressed in Section 18.104.22.168 (Stakeholders and Their Concerns Addressed).
4.19 Glossary and Acronyms
Architecture descriptions will often be reviewed by people outside the project, or even by people outside NASA. These people won’t necessarily understand all the numerous technical terms and acronyms in use, so a glossary and list of acronyms can be very helpful to readers.