A Template for Documenting Software and Firmware Architectures

A Template For Documenting Software And Firmware Architectures-Free PDF

  • Date:12 Jan 2021
  • Views:6
  • Downloads:0
  • Pages:38
  • Size:405.62 KB

Share Pdf : A Template For Documenting Software And Firmware Architectures

Download and Preview : A Template For Documenting Software And Firmware Architectures

Report CopyRight/DMCA Form For : A Template For Documenting Software And Firmware Architectures


Table of Content,Table of Content 2,1 Overview 3, 2 The Role and Content of Architectural Documentation 3. 3 Template for Architectural Documentation 5,3 1 Introduction Section 5. 3 2 System Purpose Section 6,3 2 1 Context Section 6. 3 2 2 System Interface Section 7,3 2 3 Non Functional Requirements Section 8. 3 3 Structure Section 10,3 3 1 Overview Section 10.
3 3 2 Components Section 14,3 3 3 Interfaces Section 16. 3 4 Dynamic Behavior Section 19,3 4 1 Scenarios Section 19. 3 4 2 Mechanisms Section 23,3 5 Other Views Section 25. 3 5 1 Process View Section 25,3 5 2 Development View Section 26. 3 5 3 Physical View Section 26,3 6 Conceptual Framework Section 27.
3 7 Conclusion Section 29,4 Conclusion and Acknowledgments 30. 5 References 30,Appendix A Outline Summary 31, Appendix B Conformance to the IEEE Recommendation for Architectural Description 33. Appendix C Glossary 35, Hewlett Packard 2000 HP Architecture Template Page 2 of 38. All rights reserved,1 Overview, In recent years a realization has grown of the importance of software architecture According to Bass et al. 1 the software architecture of a system is the structure or structures of the system which comprise. software components the externally visible properties of those components and the relationships among. them The IEEE recommendation 2 defines an architecture as the fundamental organization of a system. embodied in its components their relationships to each other and to the environment and the principles. guiding its design and evolution Software architectures are important because they represent the single. abstraction for understanding the structure of a system and form the basis for a shared understanding of a. system and all its stakeholders product teams hardware and marketing engineers senior management and. external partners, This paper tackles the problem of how an architecture should be documented It is a meta document that.
defines a template for producing architectural documentation As such it defines how to document purpose. concepts context and interface of a system how to specify system structure in terms of components their. interfaces and their connections and how to describe system behavior Although the paper uses the term. software architecture throughout the template has proven to be also applicable to firmware architectures. with little or no modification, The structure and content for an architectural description is given in section three of this paper Each. subsection of section three describes the form and content of a section of an architecture document Thus. section 3 1 of this template describes what information should be given in the Introduction section of an. architecture document section 3 2 describes the Purpose section of an architecture document etc Most. explanations are accompanied by examples taken from a fictitious architecture document for CellKeeper. network management system 3, A summary of the structure of an architecture document is given in appendix A Appendix A is the ideal. starting point for everybody who wants to get a quick overview of the various elements of the architecture. Section two of this paper discusses the different contents purposes and readerships for architectural. documentation and how that affects the use of the template Appendix B shows how the architecture. template presented here relates to the IEEE Draft Recommended Practice for Architectural Description. Appendix C contains a glossary of important terms, 2 The Role and Content of Architectural Documentation. Architectural overview and architectural reference manual. The template can be used to produce two different kinds of architectural documentation an architectural. overview and an architectural reference manual, An architectural overview is aimed at providing a shared understanding of the architecture across a broad. range of people including the developers marketing management and possibly potential end users An. architectural overview is ideally produced early in the development lifecycle and serves as the starting. point for the development An architectural overview should be at a high level of abstraction All the major. functionalities and components of the architecture should be described but the descriptions may lack detail. and precision as they often use natural language rather than formal notations. An architectural reference manual describes an architecture in a detailed and precise manner Unlike an. architectural overview an architectural reference manual is not written at one particular point in time. Rather a reference manual should be a living document that is constructed collaboratively by the. development team as the development proceeds As it develops the reference manual can be used to track. progress of the software development and for assessing the impact of proposed requirements changes. When complete the reference manual is the basis for system maintenance and enhancements The reference. manual should be updated as changes occur so it always reflects the actual architecture. Hewlett Packard 2000 HP Architecture Template Page 3 of 38. All rights reserved, A reference manual needs to be complete in the sense that every facet of the architecture should be.
documented Although a reference manual will tend to be detailed and technical in nature the level of. abstraction and precision is likely to vary across the architecture and across different projects The. architecture within very large grained components should be documented in separate architectural reference. manuals for the components The level of completeness formality detail and precision used for any. particular aspect of the architecture will depend on the associated technical or business risk. Not every architecture documentation requires all the sections described in this template Appendix A gives. a summary of all the sections and shows which ones are optional Yet even for the mandatory sections the. amount of information documented not only varies between architectural overview and architectural. reference manual but also from project to project The introduction section of the architecture document. lists the stakeholders and their concerns An architecture document is complete as soon as the concerns of. the stakeholders are met,Views covered by the architecture template. The template has been structured according to the 4 views of the 4 1 view model of Kruchten 4 the. logical view is modeled in the structure section and the dynamic behavior section the process view the. physical view and the development view are modeled in the other views section. For each view the structure of the components and the dynamic behavior i e scenarios showing the. interactions of the components are modeled For the process physical and development view this is done. in the process physical or development view sections For the logical view it is split up into two sections. the structure section and the dynamic behavior section Of course the dynamic models in the different. views must be consistent They can be looked at as the integrating force between the various views. Logical View Development View,Structure Section,Development View. Behavior Section,Process View Section Physical View Section. Process View Physical View,Figure 1 4 1 View Model. Hewlett Packard 2000 HP Architecture Template Page 4 of 38. All rights reserved,3 Template for Architectural Documentation.
Sections 3 1 to 3 7 describe the structure and content of an architecture document For each section of such. a document it provides a description of the structure an explanation and in all non trivial cases an. example The following notational convention is used. Syntactic structure of each part of the section is shown diagrammatically in a figure with. yellow background e g Figure 2 or as a table e g Table 1. The normal text gives explanations of the content of each section. Examples are shown in figures with a double edge e g Figure 4. Figure 2 shows the top level structure of an architecture document Each box names a section of the. document and briefly describes its purpose,Introduction System Structure Dynamic. Purpose Behavior,architectural,author creation description how the. overview logical,date modification system interface architecture. components and,etc non functional works,interfaces. requirements,Architecture i ii iii,Title Mapping Conceptual Conclusion.
Logical to Other Framework,Views Section, mapping logical concepts needed limitations of the. components to for understanding architecture open,processes files architecture issues. and hardeware,Figure 2 Sections of an architecture document. The following chapters discuss the structure and content of each section of the architecture document. 3 1 Introduction Section, The introduction section identifies the architecture and its stakeholders and it records the creation and. subsequent modification to the architecture documentation Details to be captured include. name of the architecture, architecture design team and author of the architecture document with information on who to.
contact to provide feedback for the architecture and its documentation. creation and modification history,audience and purpose. selected viewpoints,related documents, Hewlett Packard 2000 HP Architecture Template Page 5 of 38. All rights reserved, As part of the introduction the architecture document should state whether the document is an architectural. overview or a reference manual who the stakeholders and the intended readers are and what the intended. purposes of the document are It should also record the relationship to any other documents associated with. the development of the software e g System Requirements Specification System Architecture. Specification Design Specification Internal Reference Specification etc Optionally1 the selected. viewpoints see appendix B can be listed together with the stakeholders and the issues addressed by each. viewpoint and a list of the sections of the architecture document containing descriptions and models for the. selected viewpoints, When there is a single product associated with the architecture this section may optionally contain. information regarding the project product using the architecture like project name release date project. team or product team,3 2 System Purpose Section, This section documents the system in terms of its purpose and the problem that it solves It describes the.
context in which the system will be used and the problem s that it solves. the services i e functionality that the system provides at its interfaces and. the qualitative characteristics of these services, The system purpose section provides a black box view of the system to be designed The system must. satisfy the requirements as defined in any valid system requirements document If for any reason there are. requirements which are not met by the system then these must be explicitly recorded Normally the system. purpose section gives a summary of the specifications concerning context system interface and non. functional requirements contained by any system requirements specification documents 2. Context System Non functional,Interface requirements. problem description qualities constraints,System including context of. services provided by,principles that,Purpose the system. problem architecture supports,Figure 3 System purpose section.
3 2 1 Context Section, This section briefly and informally describes the context of the system and the problem that it solves. The aim is to provide an introduction to the system that is accessible to non domain experts The problem. description should enumerate the key entities involved with the system and how the system provides value. to them The focus of this section is on the entities interested in and communicating with the system and on. the roles of these entities not on the system itself. Needed for conformity with IEEE Recommended Practice for Architectural Description. Depending on purpose and audience of the architecture documentation the system purpose section can simply contain. references to the appropriate sections in requirements specification documents. if a system requirements specification contains the same information or models as required for the sections. Context System Interface and Non Functional Requirements. if such system requirements documentation is maintained and updated during the life of the system. and if these documents are readily available to the audience of the architecture documentation. Hewlett Packard 2000 HP Architecture Template Page 6 of 38. All rights reserved, In order to describe the problem solved by the system it is necessary to delineate the boundary between the. system and its environment It is sometimes also helpful to show the larger context of which the system is. part of inclusive associations and data flows between other systems The context diagram can be one of. the following, an object or class diagram showing the system under consideration other systems interacting with. this system or otherwise valuable for understanding the context and all important associations. a high level use case diagram showing the system its actors3 and the most important use cases. a data flow diagram showing the data and control flows between the system and other entities in its. A Template for Documenting Software and Firmware Architectures Version 1 3 15 Mar 00 Michael A Ogush Derek Coleman Dorothea Beringer Hewlett Packard Product Generation Solutions mike ogush hp com derek coleman hp com dorothea beringer hp com Abstract This paper defines a template for producing architectural documentation Two different kinds of architectural documentation are identified

Related Books