2013 RESIDENTIAL COMPLIANCE SOFTWARE
DEVELOPMENT PLAN
VERSION 1.0
January 2012
REVIEW DRAFT FOR PROGRAM ADVISORY COMMITTEE (PAC)
Note to PAC members: This draft document describes the key elements of this project. Feel free
to use it as a means of providing guidance to the project team. You can download this file, make
changes and comments in it, and email it to jennifer@jenniferroberts.com, who will then
distribute it to the project managers and other team members. Or you can provide comments
directly via email to Bruce and Martha (please also copy Jennifer). Thank you for your input and
involvement.
Contributors include:
Martha Brook, California Energy Commission
Bruce Wilcox, P.E.
Dave Krinkel, EnergyAi
TABLE OF CONTENTS
1
Project Overview ...................................................................................................................................................4
1.1
Purpose and Objectives................................................................................................................................4
1.2
Software Deliverables ..................................................................................................................................6
1.2.1
Compliance Manager ...............................................................................................................................6
1.2.2
CEC User Interface ...................................................................................................................................7
1.2.3
California Simulation Engine Upgrades ....................................................................................................7
1.2.4
Compliance Form Generator ...................................................................................................................7
1.3
2
Project Schedule ....................................................................................................................................................8
2.1
3
4
5
6
Future Directions..........................................................................................................................................7
Definition of Phases and Milestones ............................................................................................................8
2.1.1
Inception Phase .......................................................................................................................................8
2.1.2
Design Phase ............................................................................................................................................8
2.1.3
Construction Phase ..................................................................................................................................9
2.1.4
Transition Phase ......................................................................................................................................9
2.2
Schedule Table ...........................................................................................................................................10
2.3
Schedule Control ........................................................................................................................................10
Organization ........................................................................................................................................................12
3.1
Organizational Structure ............................................................................................................................12
3.2
Roles and Responsibilities ..........................................................................................................................12
Functional Requirements Process .......................................................................................................................13
4.1
Goal of Functional Requirements...............................................................................................................13
4.2
Requirements Gathering ............................................................................................................................13
4.3
Requirements Document Template ...........................................................................................................14
Software Specifications Process ..........................................................................................................................16
5.1
Goal of Software Specifications .................................................................................................................16
5.2
Specifications Document Template ...........................................................................................................16
Quality Assurance Process ...................................................................................................................................19
6.1
QA Plan Description ...................................................................................................................................19
6.2
Reviews and Audits ....................................................................................................................................19
6.3
Tools and Techniques .................................................................................................................................19
6.4
Testing Strategy..........................................................................................................................................20
2013 Residential Compliance Software Development Plan
2
6.4.1
Unit Testing ............................................................................................................................................20
6.4.2
Integration Testing .................................................................................................................................20
6.4.3
Acceptance Testing ................................................................................................................................20
6.4.4
Regression Testing .................................................................................................................................20
6.5
7
8
9
User Documentation ..................................................................................................................................20
Software Maintenance Plan ................................................................................................................................22
7.1
On-going Maintenance Tasks .....................................................................................................................22
7.2
On-going Release Strategy .........................................................................................................................22
Software Distribution Plan...................................................................................................................................23
8.1
Open Source Licensing ...............................................................................................................................23
8.2
Plug-in Software Distribution .....................................................................................................................23
8.3
On-going Release Distribution ...................................................................................................................23
References ...........................................................................................................................................................24
9.1
Reference Documents ................................................................................................................................24
9.2
Acronyms ...................................................................................................................................................24
2013 Residential Compliance Software Development Plan
3
1 PROJECT OVERVIEW
1.1
PURPOSE AND OBJECTIVES
California’s building stock is among the most energy efficient in the world, thanks in large part to the state’s Title
24 (Part 6) Energy Efficiency Standards. Since 1978 these Standards have saved California residents billions of
dollars in electricity and natural gas costs, and helped secure the state’s leadership position in the green building
industry.
The Title 24 Residential Standards were among the first to offer a new approach to building code compliance,
called the “performance method.” The performance method gives architects and builders greater flexibility in their
designs. They can optimize performance and achieve compliance at the lowest possible cost.
Broadly speaking, the performance method of compliance has the following three steps:
1
A “proposed design” is created from building plans. Some construction and equipment components
must meet basic requirements. For example, an exterior wood frame wall must meet or exceed a
minimum R-value, but there are no restrictions on wall area or orientation.
2
A “standard design” is created from the proposed design, as specified in a set of rules. All construction
and equipment components are modified to meet basic requirements. Even the building geometry can
be modified. For example, the current Title 24 Residential Standards require that while the floor area
and volume of the standard design be the same as the proposed design, the wall and window areas in
the standard design are distributed equally on the four compass orientations of north, east, south, and
west.
3
The annual energy use is calculated for both designs, using the same assumptions for weather data,
thermostat setpoints, internal gains, occupancy schedules, etc.
The proposed design is in compliance if its annual energy use is not greater than that for the standard design.
The performance method is the most popular compliance method under the Title 24 Residential Standards, with
more than 95 percent of building permit applications being submitted in this manner.
The performance method has broad applicability outside of Title 24 jurisdiction. Other regulatory agencies in the
U.S., Canada and elsewhere currently offer (or would like to offer) a similar approach, but using their specific
compliance “rules.” Some energy utilities offer incentive programs which require an annual energy use calculation
to determine qualification. And there is a thriving market for performance-based compliance software targeted to
the residential building industry.
Because of this broad applicability, the California Energy Commission is leading a collaborative effort to provide
open source performance method software tools for residential construction standards compliance and other
energy efficiency public policy implementation. The goal of this effort is to develop a software platform which
implements the general performance approach, but enables different organizations to employ their specific
compliance rules.
For example, the software platform would support the following efforts:

New construction compliance by a regulatory agency using its code requirements and rules.
2013 Residential Compliance Software Development Plan
4




“Green building” certification by professional associations and non-profit organizations.
Qualification of residential construction for rebates, reduced rates, and other incentives from energy
utilities.
Software “plug-ins” which enable software developers to incorporate compliance functionality into their
design tools.
Certification of third party software compliance tools for accuracy.
The platform is called “2013 Residential Compliance Software” (RCS). As part of the 2013 Residential Standards
work a Program Advisory Committee (PAC) is being formed to advise and assist in funding the development and
on-going maintenance of RCS.
In general terms, four types of software components are needed to implement the performance method – a user
interface, a “Compliance Manager,” simulation engines, and a report engine:
User Interface
Compliance Form Generator
Building project data
Compliance results
Compliance forms
Compliance Manager
Standard & proposed designs
Compliance forms
Energy performance results
Simulation Engine(s)
User Interface – enables the entry of project, construction, and equipment data for the proposed design.
Presents the final forms indicating if the design is in compliance. The user interface may be third party
software such as a commercially available building design tool.
Compliance Manager – the traffic cop for the performance method. The CM uses “data models” and
“rulesets” to generate the proposed and standard designs from the user’s inputs. It configures the data
for both designs into an input format acceptable by the simulation engines. And it transforms the results
from the simulation engine into a format acceptable by the compliance form generator, and relays the
forms to the user interface.
Simulation Engines -- perform the energy analyses for both the proposed and standard designs. One tool
might do all the required calculations, or different tools may handle different aspects of the designs. For
example, the RCS implementation will use the California Simulation Engine (CSE) for building envelope,
lighting, and heating/cooling system calculations, and a CEC Domestic Water Heating (DHW) module for
water heating calculations.
2013 Residential Compliance Software Development Plan
5
Compliance Form Generator – transforms the analyses results into standard forms which show whether
or not the proposed design is in compliance. These forms should not be editable.
The project described by this plan will deliver each of these components, though in some cases they will be
configured specifically for the California 2013 Residential Standards. Each deliverable is described in the next
section. However the objective is that all components can be configured for the other performance method
applications listed earlier in this section.
1.2
SOFTWARE DELIVERABLES
This plan describes the development, testing, documentation, and support of four software deliverables.
1.2.1 COMPLIANCE MANAGER
The Compliance Manager (CM) is the central hub of the RCS platform. While the deliverable for this project will
include configuration for the California 2013 Residential Standards, the CM can be used by any agency or
organization that uses the performance method for code or program compliance.
The CM has the following capabilities:




Accept as input basic residential building data for construction and equipment. This will most likely be an
XML file. The schema define the available components, (e.g., exterior walls, windows, heating/cooling
systems), their properties (e.g., areas, R-values, efficiencies), and relationships between components. Lists
of available options can be defined, such as a list of available framed exterior wall types with their
properties.
Apply a “rules processor” to generate both proposed and standard designs. The rules for a given design
are defined in a “ruleset.” Rules can be simple or complex. A simple rule might modify an exterior wall’s Rvalue to some default value. A more complex rule might modify exterior wall and window areas. Rules
determine which inputs are required, which are defaulted, even which can be edited. Rulesets are
configurable.
Format the data for the proposed and standard designs for input to the California Simulation Engine (CSE)
and CEC DHW module. These will most likely be XML files. But the CM will support flexible configuration
of simulation input data to support other simulation tools.
Apply the compliance rules to the simulation results for the proposed and standard designs, to determine
if the design is compliant. Format these results as required for the compliance form generator (most likely
as an XML file).
The flexibility of the CM’s rules processor is key to the broad applicability of the RCS platform. It supports
dependency chains where selections or defaults are affected by other inputs. The ruleset can incorporate look-up
tables in which multiple default values are determined by a single selection (e.g., “building type” triggering default
occupancy levels, thermostat schedules, etc.).
An agency or organization will have the ability to encrypt or otherwise protect from alteration the CM and the
specific rulesets they develop. This enables distribution of a validated compliance software tool to program
participants.
It is intended that the CM be distributed via an open source forum and licensing.
2013 Residential Compliance Software Development Plan
6
1.2.2 CEC USER INTERFACE
A simple interface is needed to enable a user to enter the basic building data required by the CM, and to return the
compliance forms from the form generator. The interface is intended for two types of users:


Energy Commission staff for certification of RCS as compliant for the 2013 Residential Standards;
Builders, architects, and other designers submitting proposed designs for compliance testing, as per
statutory requirement.
It is anticipated that the CEC user interface will employ a basic hierarchical model. The input data will be organized
by topic, such as “Project” for overall project information, “Envelope” for building envelope data, and
“Mechanical” for space conditioning and water heating equipment data.
Each topic provides access to a set of hierarchical components. For example, the Envelope hierarchy might have
components like “Exterior Wall,” “Roof,” “Slab on Grade Floor,” etc. at the highest level of the hierarchy. Exterior
walls might have children components like “Window” or “Door.”
Each component will likely have its own input screen which contains the specific properties needed by that
component. For example, an exterior wall component might have inputs for area, orientation, cavity R-value,
sheathing R-value, frame type, etc.
The CEC user interface will also display the compliance forms. It is likely that these will be an encoded PDF file
which cannot be edited.
1.2.3 CALIFORNIA SIMULATION ENGINE UPGRADES
[Description to be added]
1.2.4 COMPLIANCE F ORM GENERATOR
The form generator receives the compliance results for the proposed and standard designs from the CM as a single
packet payload. It then creates all required documents, such as compliance certificates with the building energy
performance metrics for the 2013 Residential Standards.
These documents will be uneditable, most likely as encoded PDF files. The CM will distribute the document files to
the user interface.
1.3
FUTURE DIRECTIONS
[TO BE ADDED]
2013 Residential Compliance Software Development Plan
7
2 PROJECT SCHEDULE
2.1
DEFINITION OF PHASES AND MILESTONES
The preceding section describes the four deliverables for this project – the Compliance Manager (CM), the CEC
User Interface, upgrades to the California Simulation Engine (CSE), and a compliance form generator.
Each deliverable will be developed and released over four phases. Each phase concludes with a milestone. The
phases and their milestones are described in the following subsections.
2.1.1 INCEPTION PHASE
The inception phase will define the business case for each deliverable. This requires identifying all external entities
who will interact with each software tool, and the nature of their interaction at a high-level. For example, the
primary users of the CM and CEC user interface tools include building energy experts at regulatory agencies like
the California Energy Commission, trade groups like the AIA, and utilities.
The most significant use cases for each deliverable will be documented. This will rely heavily on input from the
PAC. The use cases are important to delimit the scope of each tool. Where applicable, the use cases should include
datasets of expected results which can be used for testing during development. Representative end users for each
use case should also be recruited as potential beta testers in the construction phase.
It is also helpful during this phase to review other compliance software tools (or related building design software)
for examples of what does (or doesn’t) apply to the business case. If resources permit, prototypes should be
mocked up for PAC review.
The first major project milestone is due at the end of the inception phase, the Functional Requirements document.
A template for the Functional Requirements is provided in section 4 of this plan.
The evaluation criteria for the inception phase are Energy Commission and PAC concurrence on the functional
requirements, especially scope definition.
2.1.2 DESIGN PHASE
The design phase will start with the functional requirements from the inception phase to develop a detailed
architectural prototype of the software tool. A key step is analyzing the design vs. the use cases from the inception
phase. If some use cases threaten to expand the development scope too much for available resources, then these
riskier use cases may be excluded from the initial software release. Architectural decisions have to be made with
an understanding of the whole system: its scope, major functionality and nonfunctional requirements such as
performance requirements.
The first milestone for the design phase is a detailed Software Specifications document. This document includes




Software architecture description
Workflows for retained use cases
User interface design and standards
Data model definition
A template for the Software Specifications is provided in section 5 of this plan.
2013 Residential Compliance Software Development Plan
8
The second milestone is a Quality Assurance plan. This document details specific unit tests as well as end-to-end
testing. Test datasets collected in the inception phase will play an important role here. For example, the CM testing
should include example rulesets for proposed and standard design inputs for several compliance regimes (i.e., not
just limited to the California 2013 standards).
The Quality Assurance plan is described in section 6 of this plan.
At the end of the design phase, the hard “engineering” is considered complete. While the process must always
accommodate changes, the design phase activities ensure that the architecture, requirements and plans are stable
enough, and the risks are sufficiently mitigated, so that software coding can begin in earnest.
2.1.3 CONSTRUCTION PHASE
The construction phase is the “build it, test it, document it” phase, culminating in one or more beta releases. The
Software Specifications drive the coding, and the Quality Assurance plan drives the testing. This is necessarily an
iterative process – components are coded and then unit-tested, modified, and re-tested. In addition to coding,
static data tables are populated where applicable.
User documentation is also developed in the construction phase. This includes the following (where appropriate):




User manual, including administration and maintenance instructions
Quick start guide
On-line help
Training materials
All components and application features are integrated into the product, and the end-to-end testing should
thoroughly exercise all features. The construction phase is, in one sense, a manufacturing process with the end
result being a product ready to put in the hands of a select group of end users. So the milestone for this phase is
the beta release. The software is ready to go operational, without exposing the project to high risks.
2.1.4 TRANSITION PHASE
The purpose of this phase is to transition the software to the general user community. Once the product has been
given to the beta testers, issues usually arise that require corrections and modifications. Often some features that
were postponed are finished during this phase.
Typically, this phase includes several iterations of beta releases. The user documentation will likely also need
refinement. Considerable effort is expended in supporting beta users and reacting to their feedback. At this point
in the lifecycle, however, user feedback should be confined primarily to product tuning, configuring, installation,
and usability issues. Requests for new functionality (“feature creep”) should be noted and documented for future
consideration.
Rarely is there a concrete benchmark that determines the end of beta testing. The software is ready for general
release when there is general concurrence from the project team, the Energy Commission, and PAC that the
functional requirements are met, and the software is sufficiently stable.
The transition phase milestone is software deployment. The CM and user interface are to be distributed under
open source licensing. The specific license language and deployment mechanism are to be determined. The 2013
Standards plug-in will be made available to building energy design application software vendors.
2013 Residential Compliance Software Development Plan
9
2.2
SCHEDULE TABLE
Oct-13
Nov-13
Dec-13
Sep-13
Jul-13
Aug-13
Jun-13
Apr-13
May-13
Mar-13
Jan-13
Feb-13
Dec-12
Oct-12
Nov-12
Sep-12
Jul-12
Aug-12
Jun-12
Apr-12
May-12
Mar-12
Jan-12
Feb-12
Dec-11
Oct-11
Nov-11
Activities
Sep-11
The start and end dates for major project activities are shown below:
Compliance Manager
CSE upgrades
New Const. Rules
New Const. Beta Test
Compliance Pilots
Add’ns & Alt’s Rules
Add’ns & Alt’s Beta Test
New Const Compliance sw
Add’ns and Alt’s Software
Final Draft CM Manual
CEC Compliance sw
Certification
Deadline for CEC Software
Certification
Support
2.3
SCHEDULE CONTROL
The project schedule in the preceding section will be reviewed and updated as necessary on a bi-weekly basis with
actual start, actual finish, and completion percentages to be provided by task owners.
The project manager is responsible for




holding bi-weekly schedule updates/reviews;
determining impacts of schedule variances;
approving schedule change requests;
reporting schedule status with the Contract Manager.
The project team is responsible for



participating in bi-weekly schedule updates/reviews;
communicating any changes to actual start/finish dates to the project manager;
and participating in schedule variance resolution activities as needed.
If any member of the project team determines that a change to the schedule is necessary, the project manager and
team will meet to review and evaluate the change. The project manager and project team must determine which
tasks will be impacted, variance as a result of the potential change, and any alternatives or variance resolution
activities they may employ to see how they would affect the scope, schedule, and resources. If, after this
evaluation is complete, the project manager determines that any change will exceed the established boundary
conditions, then a schedule change request must be submitted to the Contract Manager.
2013 Residential Compliance Software Development Plan
10
Any changes in the project scope, which have been approved by the Contract Manager, will require the project
team to evaluate the effect of the scope change on the current schedule. If the project manager determines that
the scope change will significantly affect the current project schedule, he may request that the schedule be rebaselined in consideration of any changes which need to be made as part of the new project scope. The Contract
Manager must review and approve this request before the schedule can be re-baselined.
2013 Residential Compliance Software Development Plan
11
3 ORGANIZATION
3.1
ORGANIZATIONAL STRUCTURE
The technical team consists of the following people and organizations:
Name
Martha Brook
Bruce Wilcox
Chip Barnaby
Scott Criswell
Dave Krinkel
Phil Niles
Robert Scott
Ken Nittler
Marc Hoeschele
Doug Herr
John Proctor
3.2
Organization
California Energy Commission
Wrightsoft
Wrightsoft
ENERGYai
RASENT Solutions
Enercomp
Davis Energy Group
California Energy Commission
Proctor Engineering
Role
Contract Manager
Prime Contractor, Project Manager, Technical Lead
CSE Lead Programmer
Compliance Manager Lead Programmer
Development Plan
CSE Chief Scientist
Compliance Form Generator
Compliance Ruleset
DHW Simulation
DHW Programmer
HVAC modeling
ROLES AND RESPONSIBILITIES
[TO BE ADDED: IDENTIFY THE ORGANIZATIONAL UNITS THAT WILL BE RESPONSIBLE FOR EACH OF THE CORE TASKS AND SUPPORTING
PROCESSES.]
2013 Residential Compliance Software Development Plan
12
4 FUNCTIONAL REQUIREMENTS PROCESS
4.1
GOAL OF FUNCTIONAL REQUIREMENTS
Functional requirements are an explicit description of the functions and capabilities each software deliverable
must provide, as well as any constraints under which it will operate. They are essentially a blueprint for
development, maintaining focus on the core requirements while limiting “scope creep.”
The functional requirements document is often referred to as the “parent” document because all subsequent
design specifications, testing and validation plans, and user documentation, flow from it.
It’s important to note that the functional requirements are just that – “requirements” – and not a detailed product
design. The latter is provided in the software specifications discussed in the next section of this plan.
The functional requirements document accomplishes four major goals:




4.2
It provides feedback to the “customer” (the Energy Commission and PAC). It offers assurance that the
development team understands the issues or problems to be solved and the software behavior addresses
those problems. So the requirements should be stated in non-technical language that the intended end
user can understand. Charts and data flow diagrams should be included where appropriate.
It decomposes the required functionality into component parts. The simple act of writing down
requirements in a prescribed format organizes information and places borders around the problem set.
It serves as an input to the design specification. As mentioned previously, the functional requirements
serve as the parent document to subsequent documents. Therefore, they must contain sufficient detail so
that a design solution can be devised.
It serves as a product validation check. The functional requirements also serve as the parent document for
testing and validation planning.
REQUIREMENTS GATHERING
“Use cases” are the standard approach to capturing functional requirements. Use cases explain the end user's
interaction with the software. They are simply the description of steps of processes that, taken together, lead to
the software doing something useful. For example, a use case for the CEC user interface deliverable will describe
what building design data an architect or contractor needs to enter, how he or she might iterate through design
options, and what compliance results are needed.
Use cases reduce ambiguity. When confronted with a “pile” of requirements, it is often difficult to make sense of
what the intention of the requirements really is. Use cases specify when and under what conditions a sequence of
process steps will occur. This is particularly true when the steps involve a dialogue between a user and a system.
This sequence of process steps can be regarded as a requirement. This allows the behavior of the proposed
software to be expressed in a way that stakeholders can easily understand.
Use cases should include the alternate activities that need to take place when an exception occurs. Users are very
good at explaining what is supposed to happen when no exceptions occur, but tend to be weaker at automatically
thinking of all the alternates that the system has to support. Scenario modeling acts as this prompt and if done
correctly will help ensure that gaps in the requirements are identified and filled.
2013 Residential Compliance Software Development Plan
13
4.3
REQUIREMENTS DOCUMENT TEMPLATE
The Functional Requirements document for each software deliverable will follow the general organization
described below:
Section 1: Overview
The document should begin with a high level description of the software scope. This includes:






product functions – what does the tool do, what problems does it solve;
who will use the tool, a general description of the types of intended users. For example, the
Compliance Manager users include the energy experts who will configure the rulesets for a
compliance regime;
what are the user environments, i.e., desktop app, web app, mobile app;
data to be entered into the system. For example, the user interface overview should describe the
basic inputs for a building design;
reports and other outputs;
interfaces with external systems. For example, the Compliance Manager will interface with the CSE,
the CEC DHW module, the compliance form generator, and the CEC user interface.
Section 2: Use Cases
A use case describes in detail the interaction between a user and the software. It illustrates and provides
clarity to the requirements in the following section. There will usually be separate use cases for different
types of users, such as end users vs. administrators, or typical users vs. “power” users. For example, the
Compliance Manager will likely have separate use cases for




energy experts configuring and testing rulesets for generating proposed and standard designs, for
distribution to end users;
administrators configuring and testing the interface with the simulation engine;
the end user submitting a design for compliance;
reporting compliance calculation messages and results.
Each use case walks through the basic steps of a workflow, including alternate paths that are triggered by
exceptions. Diagrams are particularly helpful here. A typical use case will include:





description of the data to be entered by a given user;
description of the operations to be performed by the software;
workflow steps, including approvals and exceptions;
description of reports and other output;
restrictions on who can enter data into the software.
Section 3: System Requirements
This section describes the functional architecture of the software – what components are needed to satisfy
the use cases in the previous section. The emphasis is on “what” each component must do, not “how” they do
it (the more technical “how” is in the software specification described later in this plan).
2013 Residential Compliance Software Development Plan
14
But the “what” should be reasonably detailed. For example, the CEC user interface system requirements
should describe the functions performed by each type of screen the user will see. They should also list the
configuration capabilities of input fields – range restrictions, defaults, enumerated lists, nullability, exception
handling, etc.
The system requirements for the Compliance Manager will likely focus on three components: a rules engine,
the interface to the simulation engine, and the handling of compliance calculation results. To pick one of
these as an example, the rules engine requirements might include:




configuration file type – how are the rules entered, i.e. as text files;
rule functionality – how rules are linked to input data and tables, basic rules functions, dynamic
functions;
security – what are the security requirements to prevent a ruleset from being modified;
performance – what is the maximum amount of time it should take to generate and submit proposed
and standard designs to the simulation engine, and process the compliance calculation results.
Section 4: Other Requirements
Time and budget constraints may require excluding some use cases and corresponding functionality from the
initial software release. Or new requirements may be identified during development but are deferred for
future consideration. These requirements should be described here.
Each functional requirements document will also include a document control table listing status, revision history,
and approvals. If appropriate, a reference list and glossary of terms and acronyms should also be provided.
2013 Residential Compliance Software Development Plan
15
5 SOFTWARE SPECIFICATIONS PROCESS
5.1
GOAL OF SOFTWARE SPECIFICATIONS
Software design translates the functional requirements into software components, interfaces, and data necessary
for the construction phase. The software specifications document shows how the software system will be
structured to satisfy the requirements. It is the primary reference for code development and, therefore, it must
contain all the information required by a programmer to write code.
Broadly speaking, there are two parts to the software specifications. The first is a description of the overall system
architecture. The second, larger part provides the detailed design, including data organization, component design,
algorithms, and user interface design.
5.2
SPECIFICATIONS DOCUMENT TEMPLATE
The Software Specifications document for each deliverable will follow the general organization described below:
Section 1: Overview
A high level description of the software scope. Note that this is essentially the same as the overview for the
Functional Requirements document, but it should be repeated here to make the software specifications
document more “stand-alone.”
The overview should also include a reference to the Functional Requirements document, and any other
sources which provide important background information for the design and implementation. A list of
acronyms may also be needed.
Section 2: System Architecture
Each software deliverable is made up of components. For example, the Compliance Manager may have
separate components for a rules engine, the interface to the simulation engine, and the handling of
compliance calculation results. The System Architecture section describes this structure and explains the
relationships between the components to achieve the complete functionality of the system.
This is a high level overview of how responsibilities of the system are partitioned and then assigned to
components. The roles or responsibilities of each component are described, along with how they collaborate
with each other. The main purpose is to gain a general understanding of how and why the system was
decomposed, and how the individual components work together. Diagrams are particularly helpful here.
The System Architecture section should also discuss any critical issues and trade-offs that were considered
during the component design. For example, if other architectures were considered, it may be useful to explain
why they were not selected.
Section 3: Data Design
This section describes how the information domain of each system is transformed into data structures. For
example, the rulesets in the Compliance Manager rely on enumerated lists of properties of building materials,
heating/cooling equipment, lighting, and other entities. The data design should show how these properties
2013 Residential Compliance Software Development Plan
16
are stored, processed and organized. This is particularly important for rulesets, because of the precedence
and dependencies they can exhibit.
Where applicable, a data dictionary should also be included in this section. This is a list of database tables,
fields, keys, and indices. Important fields should be defined.
Section 4: Component Design
This section provides a detailed description of each software component. Diagrams showing the details of
component structure, behavior, or information/control flow may be included. The description should cover
any applicable software component attributes (some of which may be adequately described solely by pseudocode).
In effect, this section translates the use cases and system requirements in the Functional Requirements into
flowcharts or their textual equivalent. The discussion provided should cover the following software
component attributes:








Classification – the kind of component, such as a subsystem, module, class, package, function, file,
etc.
Responsibilities – the primary responsibilities and/or behavior of this component. What does this
component accomplish? What roles does it play? What kinds of services does it provide to its clients?
Constraints – any relevant assumptions, limitations, or constraints for this component. This should
include constraints on timing, storage, or component state, and might include rules for interacting
with this component (encompassing preconditions, postconditions, invariants, other constraints on
input or output values and local or global values, data formats and data access, synchronization,
exceptions, etc.)
Composition – a description of the use and meaning of the subcomponents that are a part of this
component.
Uses/Interactions – a description of this component’s collaborations with other components. What
other components is this entity used by? What other components does this entity use (this would
include any side-effects this entity might have on other parts of the system)? This concerns the
method of interaction as well as the interaction itself.
Resources – a description of any and all resources that are managed, affected, or needed by this
entity. Resources are entities external to the design such as memory, processors, printers, databases,
or a software library. This should include a discussion of any possible race conditions and/or
deadlock situations, and how they might be resolved.
Processing – a description of precisely how this components goes about performing the duties
necessary to fulfill its responsibilities. This should encompass a description of any algorithms used;
changes of state; relevant time or space complexity; concurrency; methods of creation, initialization,
and cleanup; and handling of exceptional conditions.
Interface/Exports – the set of services (resources, data, types, constants, subroutines, and
exceptions) that are provided by this component. The precise definition or declaration of each such
element should be present, along with comments or annotations describing the meanings of values,
parameters, etc. For each service element described, include (or provide a reference) in its discussion
to a description of its important software component attributes (Classification, Definition,
Responsibilities, Constraints, Composition, Uses, Resources, Processing, and Interface).
2013 Residential Compliance Software Development Plan
17
Section 5: User Interface Design
Describe the functionality of the software from the user’s perspective. Explain how the user will be able to
use the software to complete all the expected features and the feedback information that will be displayed
for the user.
For example, it is anticipated that the CEC User Interface will feature a hierarchical design. Navigation within
the hierarchy elements should be described. Screen layout guidelines should be presented, using example
screenshots if possible.
2013 Residential Compliance Software Development Plan
18
6 QUALITY ASSURANCE PROCESS
6.1
QA PLAN DESCRIPTION
A single Quality Assurance Plan will be developed for the RCS project. This plan specifies procedures for
requirements and design review, software testing procedures, acceptance criteria, and user documentation
review.
The purpose of the QA plan is to ensure that the RCS deliverables conform to their functional and design
requirements, and the overall goals of the Energy Commission and PAC. It defines the standards and procedures
for appraising the development work, and establishes the goals, processes, and responsibilities required to
implement effective quality assurance functions for the project.
The QA plan provides the framework necessary to ensure a consistent approach to software quality assurance
throughout the project life cycle. It defines the approach that will be used by the RCS team to monitor and assess
development processes and products to provide objective insight into the maturity and quality of the software.
The QA plan will also describe the procedures for reviewing and approving all user documentation. Such
documentation covers installation, operation and maintenance of the software.
The key topic areas for the QA plan are discussed in more detail in the following sections.
6.2
REVIEWS AND AUDITS
The Functional Requirements and Software Specifications documents described in preceding sections need both
informal and formal reviews. Informal reviews may include:


Design walk-throughs – after an initial draft of the Functional Requirements or Software Specifications
document, a walk-through of the contents by both the development team and the project manager will
review the design, use cases, etc. Review comments are recorded and the development team will ensure
that all the action items are addressed before a formal review.
Code walk-throughs – if the Software Specifications contain pseudo-code or the equivalent, a peer and
project manager review of this code is suggested. Review comments are recorded and the development
team will ensure that all the action items are addressed.
The formal review of each document is simply the final review before release to the Energy Commission and PAC.
The project manager ensures that all necessary revisions have been made.
6.3
TOOLS AND TECHNIQUES
This is primarily a list of the management, development, testing, and maintenance tools used in the RCS project.
These should include:





Project planning, e.g., MS Project;
Development environment, e.g., Visual Studio;
Programming languages;
Bug tracking tool;
Software testing tool;
2013 Residential Compliance Software Development Plan
19

6.4
Source code management.
TESTING STRATEGY
The RCS components require a range of testing approaches. The CSE is mostly comprised of complex simulation
algorithms, which are validated by their numerical results. The CEC User Interface is dominated by screen
interactions, so navigation testing is key. Each software component will need a different strategy to detect failures
and assess whether it has met its functional requirements. The following types of testing will be applied as needed
for each deliverable.
6.4.1 UNIT TESTING
The target of unit testing is a small piece of source code. This is typically one function at a time, specified by a
developer. The objective is to test each logic path and every line of code to identify and fix bugs early in the
construction phase.
Where applicable, pre-defined testing scripts including inputs and expected outputs will be used. Unit testing is
usually performed by the developers.
6.4.2 INTEGRATION TESTING
Integration testing is performed on several software components together. The objective is to test the interactions
between modules, and ultimately leads to full end-to-end system tests. Integration test scripts are often designed
from the use cases in the Functional Requirements document.
“Stress” or high volume testing for large number of users or computationally complex cases are executed during
this phase.
6.4.3 ACCEPTANCE TESTING
Acceptance testing is performed by representative users independent from the development team. The objective
is to determine if the software meets the functional requirements.
Acceptance tests should work the whole system. As with integration tests, the scripts are usually based on use
cases.
6.4.4 REGRESSION TESTING
Regression tests are designed to catch any new bugs introduced by fixes or enhancements. These are end-to-end
tests which should be run every time the software changes. In most cases, these will be the larger of the
integration test scripts. After rerunning, the results are compared to the expected outputs or behavior to ensure
that the unchanged segments function properly.
6.5
USER DOCUMENTATION
User documentation includes, where applicable:




User manuals;
Quick start guides;
On-line help;
Training materials.
2013 Residential Compliance Software Development Plan
20
The QA plan will describe the roles and procedures for reviewing and approving all user documentation.
2013 Residential Compliance Software Development Plan
21
7 SOFTWARE MAINTENANCE PLAN
[TO BE COMPLETED.]
7.1
ON-GOING MAINTENANCE TASKS
7.2
ON-GOING RELEASE STRATEGY
2013 Residential Compliance Software Development Plan
22
8 SOFTWARE DISTRIBUTION PLAN
9
[TO BE COMPLETED.]
9.1
OPEN SOURCE LICENSING
9.2
PLUG-IN SOFTWARE DISTRIBUTION
9.3
ON-GOING RELEASE DISTRIBUTION
2013 Residential Compliance Software Development Plan
23
10 REFERENCES
[TO BE COMPLETED.]
10.1 REFERENCE DOCUMENTS
References to key documents including engineering methodology, CEC RFQ, interface guidelines, etc.
10.2 ACRONYMS
2013 Residential Compliance Software Development Plan
24