Arterial Management Program
Table of Contents

Model Systems Engineering Documents for Adaptive Signal Control Technology (ASCT) Systems

Appendix A. Document Templates

CONCEPT OF OPERATIONS

PURPOSE OF THIS DOCUMENT

The Concept of Operations is a description of how the system will be used. It is non-technical, and presented from the viewpoints of the various stakeholders. This provides a bridge between the often vague needs that motivated the project to begin with and the specific technical requirements. There are several reasons for developing a Concept of Operations.

  1. Get stakeholder agreement identifying how the system is to be operated, who is responsible for what, and what the lines of communication are;
  2. Define the high-level system concept and justify that it is superior to the other alternatives;
  3. Define the environment in which the system will operate;
  4. Derive the user needs that should be accommodated by the proposed system;
  5. Provide scenarios that describe how the system is expected to operate in practical situations; and
  6. Provide criteria to be used for validation of the completed system.

CHECKLIST: CRITICAL INFORMATION

check Is the reason for developing the system clearly stated?

check Are all the stakeholders identified and their anticipated roles described? This should include anyone who will operate, maintain, build, manage, use, or otherwise be affected by the system.

check Are alternative operational approaches (such as traffic responsive or time of day coordination) described and the selected approach justified?

check Is the external environment described? Does it include required interfaces to existing systems?

check Is the support environment described? Does it include maintenance?

check Is the operational environment described?

check Are there clear and complete descriptions of normal operational scenarios?

check Are there clear and complete descriptions of maintenance and failure scenarios?

check Do the scenarios include the viewpoints of all involved stakeholders? Do they make it clear who is doing what?

check Are all constraints on the system identified?

CONCEPT OF OPERATIONS TEMPLATE
Section Contents
Title Page

The title page should follow the Agency's procedures or style guide. At a minimum, it should contain the following information:

CONCEPT OF OPERATIONS FOR THE (insert name of project) – (insert name of sponsoring agency)

Date that the document was formally approved

The organization responsible for preparing the document

Internal document control number, if available

Revision version and date issued
1.0 Scope This chapter is a brief statement of the purpose and scope of this document; and the purpose and scope of the project. This will briefly describe contents, intention and audience. A few paragraphs will normally suffice. This chapter also gives a brief overview of the system to be built. It includes its purpose and a high-level description. It describes what area will be covered and which agencies will be involved, either directly or through interfaces. A few paragraphs and a map will usually suffice.
2.0 Referenced Documents This chapter is a place to list any supporting documentation used in preparing this document and other resources that are useful in understanding the operations of the system. This could include any documentation of current operations and any strategic plans that drive the goals of the system under development.
3.0 User-Oriented Operational Description This chapter is a brief description aimed at non-technical readers who need an understanding of the current system or situation. It should briefly say what the existing system is, how it is currently used, what you are currently able to achieve with the system and (most importantly) what you want to do that can't currently be achieved with the system.
4.0 Operational Needs This chapter lists all the needs of the stakeholders that are expected to be accommodated by the proposed system. These are expressed in non-technical terms that can be understood by all readers. The needs must have a clear nexus with the goals and objectives. This list of needs is the basis for preparation of the detailed requirements. Each requirement must satisfy at least one need, and each need must be supported by at least one requirement.
5.0 System Overview This chapter is an overview of the envisioned adaptive system. It is a high level description that will describe its goals and objectives, the main features and capabilities, other systems with which it will be interfaced, the users of the system, and the scope of its coverage. Describe its conceptual architecture at a block diagram level, with a high-level data flow diagram. This should not show design details.
6.0 Adaptive Operational Environment This section describes the physical operational environment in terms of facilities, equipment, computing hardware, software, personnel and operational procedures necessary to operate the deployed system. For example, it will describe the personnel in terms of their expected experience, skills and training, typical work hours, and other activities that must be or may be performed concurrently.
7.0 Adaptive Support Environment This describes the current and planned physical support environment. This includes facilities, utilities, equipment, computing hardware, software, personnel, operational procedures, maintenance, and disposal. It also includes expected support from outside agencies.
8.0 Operational Scenarios The purpose of this chapter is to provide examples that illustrate how the system will be expected to operate and interface with the operators in typical circumstances. It is not intended to comprehensively describe the operation under all conditions. It is intended to illustrate to vendors, managers and decision-makers alike how you see your objectives being met by the system. This description is practically oriented and takes into account the practical limitations of available systems. It should not be a description of how you would like some imagined system to operate with no regard for the practical limitation of candidate systems.Each statement in a scenario should relate to a user need, although not all needs will be further described in a scenario. The statements in the description of each scenario do not directly generate requirements. Requirements are only generated by needs. The scenarios simply provide examples of how the system meets some of the needs. The scenarios will need to cover all normal conditions, stress conditions, failure events, maintenance, and anomalies and exceptions.
Appendices This is a place to put a glossary, notes, and backup or background material for any of the sections. For example, it might include analysis results in support of the concept exploration.


SYSTEM REQUIREMENTS

PURPOSE OF THIS DOCUMENT

This requirements document describes what the system is to do (functional requirements), how well it is to perform (performance requirements), under what conditions it will perform (non-functional requirements), and what other actions are required in order for the system to become fully operational (enabling requirements). This document does not define how the system is to be built. It primarily defines requirements that are necessary to satisfy the operational needs identified in the Concept of Operations. Each requirement must satisfy at least one of the needs described in the Concept of Operations.

This document sets the technical scope of the system to be built. It is the basis for verifying (via the Verification Plan) the completeness of the system and sub-systems when delivered. Every requirement must be testable and verifiable.

TAILORING THIS DOCUMENT TO YOUR PROJECT

All signal system projects need a set of requirements defining what is needed. The tailoring is in how extensively to document these requirements. One way to gauge how many requirements to write and/or how much detail to have in the requirements document is to start at the finish line. The following should be asked when starting at the top level of the system:

  • What are all the functions needed in order to satisfy the agency that the system is doing what it is expected to do?
  • How well does the system need to perform the required functions?
  • Under what conditions does the system need to operate?

Each of these questions leads to a set of requirements. This is done for the system and any sub-systems. A simple system may be fully defined using only one or two pages of requirements describing what the system is to do. In more complex systems this could be many more pages.

Another factor that drives the extent to which requirements need to be written is the amount of commercially available products that are used. These products have their own specifications, so it may be sufficient to reference them after they have been reviewed to determine if the product will meet the agency's intended need. For example, the traffic control systems that are on the market have sufficient documentation to cover the majority of functions that are required. The additional requirements would be for any modifications or enhancements needed. However, care should be taken to ensure the referenced specifications do not lock you into one vendor when several are capable of satisfying your needs.

CHECKLIST: CRITICAL INFORMATION

check Is there a definition of all the major system functions?

check With each function of the system, is there a set of requirements that describes: what the function does, and under what conditions (e.g., environmental, reliability, and availability.)?

check Are all terms, definitions, and acronyms defined?

check Are all supporting documents such as standards and concept of operations referenced?

check Does each requirement have a link (traceability) to a higher level requirement or a user-specified need?

check Is each requirement concise, verifiable, clear, feasible, necessary, unambiguous and technology independent?

check Are all technology dependent requirements identified as constraints?

check Does each requirement have a method of verification defined?

check Does each requirement trace to a verification case?

SYSTEM REQUIREMENTS TEMPLATE
Section Contents
Title Page

The title page should follow the Sponsoring agency procedures or style guide. At a minimum, it should contain the following information:

SYSTEM REQUIREMENTS for (insert name of project) – (insert name of Sponsoring agency)

Date that the document was formally approved

The organization responsible for preparing the document

Internal document control number, if available

Revision version and date issued
1.0 Scope of System or Sub-system

Provides a system overview and briefly states the purpose of the system

Describes the general nature of the system

Summarizes the history of system development, operation, and maintenance

Identifies the project stakeholders, acquirer, users and support agencies

Identifies current and planned operating sites
2.0 References Identifies all needed standards, policies, laws, concept of operations, concept exploration documents and other reference material that supports the requirements.
3.0 Requirements

List all the requirements with which a vendor must comply. Include requirements covering each of the following types:

Functional requirements (What the system shall do)

Performance requirements (How well the requirements should perform)

Non-Functional requirements (Reliability, safety, environmental (temperature)

Enabling requirements (Production, development, testing, training, support, deployment, and disposal.) This can be done through references to other documents or embedded in this requirements

Constraints (E.g. Technology, design, tools, and/or standards)

If this document is describing a sub-system, the following may also be required:

Data requirements (Data elements and definitions of the system)

Interface requirements (Definition of the interfaces)
4.0 Verification Methods

For each requirement, identify one of the following methods of verification:

Demonstration is a requirement that the system can demonstrate without external test equipment.

Test is a requirement that requires some external piece of test equipment. E.g. logic analyzer, and/or volt meter.

Analysis is a requirement that is met indirectly through a logical conclusion or mathematical analysis of a result. E.g., algorithms for congestion: the designer may need to show that the requirement is met through the analysis of count and occupancy calculations in software or firmware.

Inspection is verification through a visual comparison. For example, quality of welding may be done through a visual comparison against an in-house standard.
5.0 Supporting Documentation

Catch-all for anything that may add to the understanding of the Requirements without going elsewhere (Reference section)

Examples: diagrams, analysis, key notes, memos, rationale, stakeholders contact list
6.0 Traceability Matrix This is a table that traces the requirements in this document to the needs in the Concept of Operation.
7.0 Glossary Terms, acronyms, definitions


VERIFICATION PLAN

PURPOSE OF THIS DOCUMENT

This verification plan describes the activity of verifying that the system being built satisfies all the requirements set out in the requirements documents. A critical issue is assuring that all requirements are verified by this activity. This is best done by tracing each requirement into a verification test case, then traced into a step in a verification procedure.

TAILORING THESE DOCUMENTS TO YOUR PROJECT

The Verification Plan and procedures may be minimal for the simplest projects, especially where the system is commercially available and does not involve any custom software development, and where the agency staff have a very clear understanding of the purpose of the system. In some cases, the vendor will provide an acceptance test plan for their features and any custom features requested by the agency. The agency should review the vendor's verification plan to ensure all the features are being verified.

Preparation a Verification Plan is advisable if:

  • The system is complex;
  • There are a number of separate verification activities being performed on the system;
  • Multiple deployment sites are involved; or
  • Multiple stakeholders have to be satisfied.

The Verification Plan does not need to include verification procedures. These may be prepared by the vendor, but must be reviewed by the agency to ensure each verification case will be tested and appropriate results recorded. In relatively simple cases, both the Verification Plan and the procedures may be prepared by the vendor. In this situation the agency must ensure that each requirement is mapped to verification test.

CHECKLIST: CRITICAL INFORMATION

check Does the Verification Plan answer all the questions of who, what, where, and when?

check Does the Verification Plan make clear what needs to happen if a failure is encountered?

check Does the Verification Plan document the configuration of the hardware and software?

check Are all requirements traced to a verification case?

VERIFICATION PLAN TEMPLATE
Section Contents
Title Page

The title page should follow the Sponsoring agency's procedures or style guide. At a minimum, it should contain the following information:

VERIFICATION PLAN FOR THE (insert name of project) - (insert name of Sponsoring agency)

Date that the document was formally approved

The organization responsible for preparing the document

Internal document control number, if available

Revision version and date issued
1.0 Purpose of Document This section identifies the type of verification activity to be performed within this Verification Plan. For instance, this activity may validate the entire system, a sub-system, the deployment at a site, a burn-in, or any other verification activity called for in the Verification Plan.
2.0 Scope of Project This section gives a brief description of the planned project and the purpose of the system to be built. This section also describes the environment in which the project operates. It identifies the organization structures that encompass all stakeholders. It also gives a brief description of the role to be played by each stakeholder. This includes ad hoc and existing management work groups and multi-disciplinary technical teams that should be formed to support the project.
3.0 Referenced Documents This is a list of all documents used in the preparation of this Verification Plan. This almost always includes the Project Plan, (if one was written), and the applicable Requirements Documents. Reference to other documents, such as descriptions of external systems, standards, a Concept of Operations, and manuals may also be included.
4.0 Conducting Verification

This section provides details on how verification is accomplished. It defines: who does the verification; when and where it is to be done; the responsibilities of each participant before, during, and after verification; the deployed hardware and software configuration; and the documents to be prepared as a record of the verification activity.

It is also important to define how anomalies are to be handled (that is, what to do when a failure occurs during verification).

In general, the following information should be included in this section:

 

  • A description of the participating organizations and personnel and identification of their roles and responsibilities. This may include for example, a verification conductor, verification recorder, operators, and/or engineering support.
  • Identification of the location of the verification effort, that is, the place, or places, where the verification must be observed.
  • The deployed hardware and software configuration for all of the verification cases, including hardware and software under verification and any supporting equipment, software, or external systems. Several configurations may be necessary.
  • Identification of the documents to be prepared to support the verification, including Verification Procedures, a Verification Report and descriptions of special equipment and software.
  • Details of the actual conduct of verification, including:
  • Notification of participants
  • Emphasis on the management role of the verification conductor
  • Procedures for approving last minute changes to the procedures
  • The processes for handling a failure, including recording of critical information, determination of whether to stop the verification, restart, or skip a procedure, resolution of the cause of a failure (e.g. fix the software, reset the system, and/or change the requirements), and determination of the re-verification activities necessary as a result of the failure.
5.0 Verification Identification

This section identifies the specific verification cases to be performed. A verification case is a logical grouping of functions and performance criteria (all from the Requirements Documents) that are to be verified together. For instance, a specific verification case may cover all the control capabilities to be provided for control of the adaptive control system. There may be several individual requirements that define this capability, and they all are verified in one case. The actual grouping of requirements into a case is arbitrary. They should be related and easily combined into a reasonable set of procedure actions.

Each case should contain at least the following information:

  • A description name and a reference number
  • A description of the objective of the verification case, usually taken from the wording of the requirement, to aid the reader understanding the scope of the case
  • A complete list of requirements to be verified or traceability to the requirements in the requirements document. Since each requirement has a unique number, they can be accurately and conveniently referenced without repetition.
  • Any data to be recorded or noted during verification, such as expected results of a step. Other data, such as a recording of a digital message sent to an external system, may be required to validate the performance of the system.
  • A statement of the pass/fail criteria. Often this is just a statement that the system operates per the need or scenario.
  • A description of the verification configuration. That is a list of the hardware and software items needed for verification and how they should be connected (in most cases this is the deployed system configuration). Often, the same configuration is used for several verification cases.
  •   A list of any other important assumptions and constraints necessary to conduct the verification case.


VALIDATION PLAN

PURPOSE OF THIS DOCUMENT

This document describes the activity of validation that the system being built meets the user needs and scenarios developed in the concept of operations. Usually, for even moderately complex systems, the following three levels of validation documents are prepared:

  • A plan to initially lay out the specific validation effort
  • The user's/operator's manual and/or a validation plan that defines the detailed operational procedures.
  • A report on the results of the validation activities

A critical issue is assuring that user needs and scenarios are validated by this activity. This is best done by first tracing each need and scenario into a validation case, then into a step in the validation procedure.

TAILORING THESE DOCUMENTS TO YOUR PROJECT

A separate Validation Plan and procedures may be minimal for the simplest projects, especially where the system is commercially available and does not involve any custom software development, and where the agency staff have a very clear understanding of the purpose of the system. Preparation a validation plan is strongly advised if:

  • The system is complex;
  • There are several separate validation activities;
  • Multiple deployment sites are involved; or
  • Multiple stakeholders have to be satisfied.

There is also the question of how comprehensive to make the validation effort. It is impossible to validate all possible combinations of actions under all possible operational situations. A good rule of thumb is: if it was important enough to write down as a need or scenario, then it should be validated, at least once. This may not, for example, validate all possible failure mode conditions or all possible incident scenarios. In-process validation performed on the needs, will help ensure that end to end validation of the system will meet the stakeholder needs.

CHECKLIST: CRITICAL INFORMATION

check Does the Validation Plan answer all the questions of who, what, where, and when?

check Does the Validation Plan make clear what needs to happen if an unexpected situation or a failure is encountered?

check Does the Validation Plan document the configuration of the hardware and software?

check Are all applicable needs and scenarios traced to a validation case?

VALIDATION PLAN TEMPLATE
Section Contents
Title Page

The title page should follow the Sponsoring agency's procedures or style guide. At a minimum, it should contain the following information:

VALIDATION PLAN FOR THE (insert name of project) – (insert name of Sponsoring agency)

Date that the document was formally approved

The organization responsible for preparing the document

Internal document control number, if available

Revision version and date issued
1.0 Purpose of Document This section identifies the type of validation activity to be performed within this Validation Plan. For instance, this activity may validate the entire system, a sub-system, the deployment at a site, a burn-in, or any other validation activity called for in the Program Plan or in the SEMP.
2.0 Scope of Project

This section gives a brief description of the planned project and the purpose of the system to be built. Special emphasis is placed on the project's user needs and issues that must be addressed and validated.

This section also describes the environment in which the project operates. It identifies the organization structures that encompass all stakeholders. It also gives a brief description of the role to be played by each stakeholder. This includes ad hoc and existing management work groups and multi-disciplinary technical teams that should be formed to support the project.

3.0 Referenced Documents This is a list of all documents used in the preparation of this Validation Plan. This almost always includes the Project Plan, the SEMP (if one was written), and the applicable Requirements Documents. Reference to other documents, such as descriptions of external systems, standards, a Concept of Operations, and manuals may also be included.
4.0 Conducting Validation

This section provides details on how Validation is accomplished. It defines: who does the validation; when and where it is to be done; the responsibilities of each participant before, during, and after validation; the deployed hardware and software configuration; and the documents to be prepared as a record of the validation activity. This section defines how anomalies are to be handled (that is, what to do when an unexpected situation or a failure occurs during validation).

In general, the following information should be included in this section:

  • A description of the participating organizations and personnel and identification of their roles and responsibilities. This may include for example, a validation conductor, validation recorder, operators, and/or engineering support.
  • Identification of the location of the validation effort, that is, the place, or places, where the validation must be observed.
  • The deployed hardware and software configuration for all of the validation cases, including hardware and software under validation and any supporting equipment, software, or external systems. Several configurations may be necessary.
  • Identification of the documents to be prepared to support the validation, including Validation Procedures, a Validation Report and descriptions of special equipment and software.
  • Details of the actual conduct of validation, including:
  • Notification of participants
  • Emphasis on the management role of the validation conductor
  • Procedures for approving last minute changes to the procedures
  • The processes for handling an unexpected situation or a failure, including recording of critical information, determination of whether to stop the validation, restart, or skip a procedure, resolution of the cause of a failure (e.g. fix the software, reset the system, repeat the procedure when conditions return to the planned state and/or change the requirements), and determination of the re-validation activities necessary as a result of the failure.
5.0 Validation Identification

This section identifies the specific validation cases to be performed. A validation case is a logical grouping of functions and performance criteria (all from the Concept of Operations Documents) that are to be validated together. For instance, a specific validation case may cover all the control of traffic during the AM peak hour. There may be several individual objectives and associated performance measures that define this capability, and they all are validated in one case. The actual grouping of objectives into a case is arbitrary. They should be related and easily combined into a reasonable set of procedure actions.

Each case should contain at least the following information:

  • A description name and a reference number
  • A complete list of needs and scenarios to be validated. For ease of tracing of needs and scenarios into the Validation Plan and other documents, the needs and scenarios are given numbers, so they can be accurately and conveniently referenced without repetition.
  • A description of the objective of the validation case, usually taken from the wording of the need or scenario, to aid the reader understanding the scope of the case
  • Any data to be recorded or noted during validation, such as expected results of a step. Other data, such as a recording of traffic volumes by the system, may be required to validate the performance of the system.
  • A statement of the pass/fail criteria. Often, this is just a statement that the system operates per the need or scenario.
  • A description of the validation configuration. That is a list of the hardware and software items needed for validation and how they should be connected. Often, the same configuration is used for several validation cases.
  • A list of any other important assumptions and constraints necessary for conduct of the validation case

previous | next