Software Engineering Process Inclusion - lgwagner/SpeAR GitHub Wiki

This section discusses the SpeAR features that were developed to support its inclusion in the software engineering process. These include capturing requirement attributes, exporting requirements to a spreadsheet, and traceability.

Mainstream requirements tools such as DOORS and JAMA include several attributes for requirements such as author, date, parent requirement(s), etc. As we applied SpeAR to the development of a new system, we found that it would be helpful to capture this kind of attribute data in SpeAR as well. Table 1 lists the attributes available in SpeAR and together with the meaning of each.

Table 1: Attributes and Meaning

Attribute	Meaning
Text	English language (non-formal) description of the requirement
Owner	Name of the requirement owner—for example, “AFRL”
Parents	List of IDs of the parent requirements. May also use a string, such as "Originating" for an originating requirement or "Derived" for a requirement derived by the contractor.
Review Date	Date on which the item and its attributes were reviewed
Source	Reference to a source document or discussion
Rationale	Rationale for why this requirement was added
Comments	Additional information that may be helpful to the reader
Trace	This may be used as an alternative attribute name for ‘Parents’ or ‘Source’

Below is an example showing how the attributes can be used with some English-language requirements for a microwave.

These attributes are also available for use with assumptions, properties, constants, patterns, type definitions, constants, and macros.

As we began to use SpeAR on projects, interfacing with systems engineers in various roles, we found that several individuals wanted to view the SpeAR requirements in a spreadsheet. This enables the user to view the English-language (non-formalized) requirements without needing to download SpeAR. This also allows the user to filter requirements and to organize them in the way that is most helpful for their work. One view in particular that users find useful is a hierarchical view that organizes children and grandchildren requirements under each top-level parent requirement.

For these reasons we developed an Excel export feature. With this Excel export feature, the push of a single button in SpeAR generates and opens an Excel file with a hierarchical view of all assumptions, requirements, and properties containing text descriptions. The export is recursive and includes everything at the current level and below (i.e., for all recursively imported files). To export the requirements for a given file (and all the imported files below it), simply open the file in the editor and click on the spreadsheet icon in the menu bar. Alternatively, select SpeAR -> Generate Excel from the menu. This will automatically open Excel with a spreadsheet of the exported requirements.

The columns in the spreadsheet of exported requirements are listed in Table 1 together with the meaning of each column. Note that in some cases the word “requirement” is used interchangeably with the lengthier phrase “requirement, property, or assumption.” In most cases, the column data is a straightforward export of the attribute data captured with each requirement. The “Children” data is computed from all parent ID references contained in the hierarchy (at or below the top-level file from which the export was conducted).

Table 2: Columns in the Requirements Spreadsheet

Column Header	Contains
ID	ID of the requirement, property, or assumption
Requirement/Property/Assumption Text	Text of the requirement, property, or assumption
REQT/PROP/AS	Tag to indicate whether this is a requirement, property, or assumption
Owner	Name of the requirement owner
Component	Name of the specification in which the requirement resides
Parents	List of IDs of the parent requirements. "Originating" indicates this is an originating requirement from the customer. "Derived" indicates this is a requirement derived by the contractor.
Children	List of IDs of child requirements (computed by the export feature using the 'parents' attribute)
Review Date	Date on which the item and its attributes were reviewed
Source	Reference to a source document or discussion
Rationale	Rationale for why this requirement was added
Comments	Additional information that may be helpful to the reader

The hierarchical view may contain duplicate rows since a requirement may have multiple parent requirements. One can easily produce a list of the unique requirements by using Excel’s “Remove Duplicates” feature and selecting the “ID” field. This assumes all requirements have been given a unique ID. A best practice is to include an abbreviation of the specification (or component) name in the requirement ID to prevent collisions of IDs across multiple files. SpeAR ensures IDs are not used more than once within a file.

Traceability is a feature of the Logical Entailment analysis that is useful for understanding which requirements were necessary to prove each property. Traceability analysis identifies which requirements were necessary to prove each property.