ESA PSS-05-0 Issue 2
February 1991
ESA SOFTWARE ENGINEERING STANDARDS
ISSUE 2 Part 3
APPENDIX B
SOFTWARE PROJECT DOCUMENTS
(Revised and annotated by K. Meinke
Local Version 1.0. December 2000
Version 1.2. Revised and Corrected November 2008.)
APPENDIX C
DOCUMENT TEMPLATES
All documents should contain the following service information:
a - Title page, project title, authors, version number, date of printing, project group name, all project members.
b - Abstract
c - Table of contents
d - Document Status, working draft, final draft, revised version. (Suggestion: 0.x = preliminary draft, 1.0 = submitted final draft, 1.x = subsequent changes)
e - Document Change Record, changes made since last issue
If there is no information pertinent to a section, the following should appear below the section heading: `This section not applicable', with the appropriate reasons for this exclusion.
Comments on the tables of contents are enclosed in parentheses. Section titles which are to be provided by document authors are enclosed in square brackets.
APPENDIX C.1
URD table of contents
1 Introduction. This chapter should give an overview of the whole document
1.1 Purpose. The purpose of this document, target audience, how to read it and use it.
1.2 Scope of the software. An "executive summary" of the product under development. Not more than 30-40 words.
1.3 Definitions, acronyms and abbreviations. Especially technical terms and acronyms (XML, ASP, TTCN UML, CORBA, etc etc) unfamilar to the reader and/or customer.
1.4 References. Sources of additional information helpful in reading this document, with a brief explanation of the contents and usefulness of each. Could be customers in-house reports, reports from previous projects, scientific or technical reports, industry white papers, computer science or other books, on-line references (URLs) and related web sites, newspaper articles.
1.5 Overview of the document. Provides a birds-eye view of what information is given in this report, and where in the report it can be found. Description can be focussed towards different types of reader, e.g. end-user, technical, developer, specialist, domain expert, accountant, legal, management, customers customer etc.
2 General Description
2.1 Product perspective. Describes related external systems and subsystems. How the product under development fits into an existing environment.
2.2 General Capabilities. Describes the main capabilities required and why they are needed from the end users perspective. Gives an overview of the product under development. Takes a user-centric approach.
2.3 General constraints. Describes the main constraints that apply to the product, and why they exist. Includes limitations on functionality due to limited project scope (time, personnel, money) and limited customer needs (ambition, money, skill level). Also includes any technological and scientific constraints, e.g. performance, bandwidth, computational difficulty of problem solving, lack of efficient algorithms, etc
2.3 User characteristics. Describes who will use the software, expected background, previous training and level of skill (may be several). Identify different job roles and contexts of use (can be used to develop a use case analysis). Used to determine user interface requirements, online/offline user support and product documentation.
2.4 Assumptions and dependencies. Describes the assumptions upon which the requirements depend. For example technical assumptions on levels of hardware performance, system availability and reliability. May include commercial assumptions about customers business needs/ business model/ business process.
2.5 Operational environment. Describes what any external systems do, in terms of functionality, (e.g. file servers, databases, etc) Describes the interfaces made available to the product under development.
3 Specific Requirements Provides a detailed list of specific requirements organised into two categories.
3.1 Capability requirements. Functional requirements on the system, (what the system should actually do) including interface requirements (e.g. file formats, data definitions, APIs, communications protocols etc.) in so far as these are known at an early stage.
3.2 Constraint requirements. Non-functional requirements, including:
3.x.y.(z) Individual Requirement Template (x = 1,2)
| Identifier | Symbolic identifier using helpful abbreviation. |
| Requirement Description | A structured description that includes symbolic references to related requirements to aid explanation. |
| Justification | An optional justification (or motivation) of why this requirement is needed. |
| Need | Use a scheme such as Standard/Economy or Deluxe/Standard/Economy. |
| Priority | High priority means early delivery needed, low means late delivery acceptable. |
| Stability | Unstable requirements that can change must be flagged. |
| Source | Origin of requirement. Could be an individual group member, whole group or external. |
| Verifiability | Explains how to verify requirement. Each requirement must be verifiable. It must be possible to: (1) check requirement is in the design, (2) test that the software does implement the requirement. |
APPENDIX C.2
SRD table of contents
Similar to URD Section 1, but set in the context of this SRD report.
1.1 Purpose. See URD Section 1.1.
1.2 Scope of the software. May be revised from URD Section 1.2. in the light of feasibility studies, project planning, requirements analysis, etc.
1.3 Definitions, acronyms and abbreviations. May extend/delete information from URD Section 1.3.
1.4 References. May extend/delete information from URD Section 1.4.
1.5 Overview of the document. Similar to URD Section 1.5, but describes the SRD. However, it need not be assumed that readership on the customer side exists. In practise, document may be company confidential to the development team.
2 General Description
2.1 Relation to current projects. Describes the relationship with other current projects (either customer side or developer side). Customer side could be outsourced component of a larger project. Developer side could be related to similar development work allowing synergies in work, software re-use, etc.
2.2 Relation to predecessor and successor projects. Describes the relationship with past and future projects (either customer side or developer side). Similar to 2.1 above, but looking away from the present time.
2.3 Function and purpose. Describes the main functions the product must perform, gives an overview. (Details are set out in Section 3.) Takes a developer-centric approach.
2.4 Environmental considerations. Describes where the product will be used (business environment and/or geographical location), who will use it (job roles, skill levels), who will operate and maintain it, hardware it will run on, operating system required.
2.5 Relation to other systems. Describes related external systems and subsystems. (A revision of URD Section 2.1)
2.6 General constraints. Describes the main constraints that apply and why they exist. (A revision of URD Section 2.3)
2.7 Model description. Describes the logical or conceptual model using a recognised analysis method. Provides a top level description of the model. (Details can be presented in Section 3.) This could be for example the results of an object-oriented analysis of the user requrements from the URD using UML, with data dictionary, role identification, use case analysis and an object model/class diagrams.
May include other kinds of model, such as state machines, flow diagrams, business process analysis, abstract data type model, formal specifications, etc etc.
Lists the specific requirements, classified by attribute type. This section may also be redesigned to list requirements classified by functional component type. (Approach is a matter of taste, and/or product type)
3.1 Functional requirements. What each logical component does.
3.2 Performance requirements. Time, space, load, reliability aspects of components.
3.3 Interface requirements. Proposal for interface structure, information organisation, workflow analysis, design philosophy, (may include prototype designs).
3.4 Operational requirements. Minimum levels of functionality and performance to be provided by external systems and subsystems (if any).
3.5 Resource requirements. Platform, OS, network, browser requirements, etc.
3.6 Verification requirements. Plan and methods for verifying and validating the system against the SRD based on user evaluation, testing and if necessary formal verification.
3.7 Acceptance testing requirements. Plan and methods for verifying that the final system meets the end-user requirements as specified by the URD
3.8 Documentation requirements. Proposal for documentation approach suitable for the job roles and skill levels identified for end users.(See SRD Section 2.4 and URD Section 2.4)
3.9 Security requirements. Requirements on data security, access security, security of external system and overall environment. May include firewall and cryptology techniques, password protection, data encryption, underlying OS security etc.
3.10 Portability requirements. Cross platform compatibility.
3.11 Quality requirements. Includes design quality, software quality, performance quality, report quality, documentation quality, usability quality. Plans and methods to impose quality. Standards for measurement and reporting.
3.12 Reliability requirements. Includes uptime, mean time to failure, accessibility, loading, average performance, worst case performance, etc.
3.13 Maintainability requirements. Levels of code documentation, software commenting, commenting standards needed to maintain, repair and upgrade the code.
3.14 Safety requirements. Hazard situations, plans and methods to avoid system failure under hazard. Levels of safety assurance.
4 User Requirements vs Software Requirements Traceability matrix. Gives a table cross referencing software requirements to user requirements.
User requirements
| UR1 | UR2 | UR3 | |
| SR1 | x | x | |
| SR2 | x | ||
| SR3 | x | ||
| SR4 | x | ||
| SR5 | x |
Software
requirements
APPENDIX C.3
ADD table of contents
1 Introduction.
Similar to SRD Section 1, but set in the context of this ADD report.
1.1 Purpose. See URD Section 1.1.
1.2 Scope of the software. May be revised from SRD Section 1.2. in the light of feasibility studies, architectural analysis and design, research and development work, etc.
1.3 Definitions, acronyms and abbreviations. May extend/delete information from SRD Section 1.3.
1.4 References. May extend/delete information from SRD Section 1.4.
1.5. Overview of the document. Similar to SRD Section 1.5, but describes the ADD. Again it need not be assumed that readership on the customer side exists. In practise, this document may again be company confidential to the development team.
2 System Overview. Summarises: (i) the system context (how it fits into an existing framework of other packages and systems), and (ii) the system design. More detailed descriptions of (i) and (ii) are given in Sections 3 and 4 below.
3 System Context. Gives a detailed description of the system context, with relevant diagrams. Defines the external interfaces of the product under development to these other systems.
3.n External interface definition. Provides an interface definition to each separate external component type or physical component.
4 System Design Provides an overview of the design techniques used, especially any in-house or non-standard methods, project specific methods, or non-standard interpretation of standard languages/methods such as UML.
4.1 Design method. Describes and references the design method.
4.2 Decomposition description. Gives the top level view of the systems design, preferably with diagrams. Shows the major components which will be described in detail in Section 5. Identifies control and data flow between components.
Gives detailed component information according to a fixed template. Components may be top level components, identified in Section 4.2, or subcomponents of these. Preferably use a component identification scheme which is easy to read/follow/remember.
5.n [Component identifier] Fill in name here.
5.n.1 Type. Could be a module, an input/output/temporary file, a program, a class, a script, a web page, etc.
5.n.2 Purpose. Describe the purpose of the component, and relate this to a numbered software requirement in the SRD.
5.n.3 Function. Describe the functionality of the component, including its interface properties (call and return types) and logical behaviour.
5.n.4 Subordinates. List the immediate subcomponents of the component, using defined component identifiers.
5.n.5 Dependencies. Describe the logical preconditions for using this component, e.g. files and/or objects which must exist.
5.n.6 Interfaces. Define the control and data flow to and from the object. Gives a detailed picture of its context in the overall system architecture.
5.n.7 Resources. List any resources required by the component, such as external components external subsystems, hardware, etc.
5.n.8 References. reference any documents needed to understand the component.
5.n.9 Processing. Describe the control and data flow betwen immediate subcomponents of this component. If the component has no immediate subcomponents (i.e. it is fully decomposed) then outline the method of processing used by the component to perform its task (e.g. with pseudo-code, state diagrams, etc).
5.n.10 Data. Describe in detail (where possible) the local data values and data structures belonging to (local in scope) this component. Otherwise give an outline description.
6 Feasibility and Resource Estimates. Summarise the conclusions of a feasibility study around the architectural model. Prioritise all components with a priority model (e.g. economy, standard, deluxe versions).
Identify and describe all future project tasks. Identify task dependencies in terms of commencement and completion, preferably with a task flow chart. Estimate the effort required for each project task. Produce a task allocation plan and schedule for each project staff member for the remainder of the project. This information should preferably be presented in a table.
Identify possible risks going forward, and for each risk, give a risk management proposal.
Estimate the overall schedule for making a detailed design, coding this design, testing and delivering the final product and documentation according to the project deadlines. Identify the critical path in the project, and analyse possible project slippage along this path.
7 Software Requirements vs Components Traceability matrix. Gives a table cross referencing architectural components (based on defined component identifers) to software requirements numbered in the SRD.
Software requirements
| SR1 | SR2 | SR3 | SR4 | SR5 | |
| AR1 | x | x | |||
| AR2 | x | ||||
| AR3 | x | ||||
| AR4 | x | ||||
| AR5 | x | ||||
| AR6 | x | ||||
| AR7 | x |
Architectural
requirements