Further notes

Talked to beam L3, L4 folks 6/10

Question about requirements vs dependencies and how to hook them to other subsystems/subprojects. Not yet clear.

Met with JDEM folks 6/1 or so

They advocate

Talked to Elaine 5/20

For straight flow of phys req to func req to spec, have one req of each kind UNLESS there's other branching that would require splitting, say, a func req into multiple ones
CDR: don't focus on R&D, R&D set to stop at CD-1. Design continues.
PM needs to provide guidance to project for CDR
LaTeX: ok if I schedule a trip to BNL to nail stuff down with Brett
At collab mtg, beam won't be represented; so concentrate on ND
Talk with Vaia about getting her people on board with LaTex, but wait till June or so; they have to pick a ref design first.
Talk with Steve Acheson about numbers in DOORS

From meeting with IBM's Ed Gafron at Fermilab 4/14/11

Attending: Ed, Erik G, Joe H, Barry N, Alan H, Bob D, Anne H

DOORS v 9.3 comes with a couple of built-in report formats, but best to get RPE (extra $$, probably worth it)
Ed recommends doing a Quick Start course with an on-site consultant to get DOORS set up the way you want it (again, extra $$, probably worth it)
RPE docs can use several templates, e.g., title page, can use variables, can produce hyperlinks. Recommends 15-to-1 ratio for users to RPE licenses.
RPE outputs in several formats: Word, pdf, html, xml
We shouldn't need too many licenses; Web (DWA) license can use a floating client one, if available.
DWA can do about 70% of client's functionality, but too cumbersome for heavy use. Good for reviewers that just need to change things here and there. "Read-only" license available too.
Warning: at each level of requirements from high to low, the number increases ~ X10
Erik suggests DXL script for 2nd numbering scheme (besides the auto-numbering); makes it easier to look through a set and gauge how many there are.
Tracebacks and views are important aspects of DOORS (that makes it more than a glorified spreadsheet), but it won't do impact-analysis for you
Can set up email notification (but without DXL, you need to fill in "To")
Can define different types of links (e.g., parent-child, complies vs satisfies)
Can set up conditional logic for filtering
Can manage change inbetween baselines

About my schema

Recommends splitting data entry into 2 phases: basic info (get from contributors via spreadsheet) then other fields to fill in within DOORS (e.g. links)
Move my headings into separate objects -- don't need one for every item.
He, Alan and Erik recommend adding text as other objects so that the document produced contains some narrative.
Alan asked me to provide more guidance on how to fill in spreadsheet cells; i.e. what they'll be used for.
Use variety of attribute types in DOORS (e.g., enumeration) as appropriate.
Add "priority" to list of attributes
Come up with standard base template (I've sort of done that...)
Ed and I (Anne) will meet again next week to go over my schema more thoroughly

(end 4/14/11 meeting notes)

From IBM seminar on DOORS 3/10/11

New version of DOORS is 9.3 (at FNAL we've been using 9.2)
IBM will make available presentations from this seminar. I didn't take a lot of notes...
License for web access (Edit?) portion is about 1/5 the price of "rich client". Very functional; not sure about licensing for "Review" (Rich Stanek may know)
The web access portion will satisfy the requirement of "everybody shall be able to view info"; (1.4 DWA w/ Firefox and IE support)
Whole suite of Rational products, being developed under Jazz framework
Lots of add-on products available to stretch functionality; pay only for installation/consulting/training, not for product (River North Solutions). Things like automating imports, metrics dashboard, auto-resync of reused reqs, ambiguous word detector...
DOORS moving toward non-proprietary database
New 9.3 features include threaded discussions, enhanced web access, merging changes.
RPE (Rational Publishing Engine) integrated into 9.3. Publish --> Generate Doc (create or choose pre-config'ed template) Export --> Doc Generation to create doc based on template. Can add conditional output, hyperlink to req, traceability matrix.
Can put in active hyperlinks in DOORS cells (better than just docdb number; could link to doc itself)
Visit Developer Tips forum -- can find DXL scripts
Cheri had something about controlling links, I missed it.
Vince went to documentation breakout; am hoping for some good notes from him.

Scott listed major challenges to the requirement-test-design cycle:

req misunderstood by stakeholder
poorly expressed
missed for test coverage
misunderstood or missed by developers

He proposes model-based approach for plugging gaps. Organize reqs into functional groups then models in Rhapsody.

Chuck Hilger (of IBM) is interested in promoting Focalpoint -- a decision-support process workspace to DOE labs. chilger@us.ibm.com 248-924-2999

3/1/11 Added "definition" to "Type" list.

Anne's notes from meeting

If I got something wrong, PLEASE CORRECT IT! Feel free to offer additional comments.

11 ReadyTalk attendees (me, Amelia, Vaia, Bruce, Bob D, Russ, Christopher, Milind, Steve K, Michael C)
General agreement that this effort needs to go ahead
General agreement on the discussion points below (goals, plan, format, style and so on)
... but some disagreement on level of uniformity and formality to aim for
New requirement on whatever requirements doc/mgmt tool we choose: it "shall" allow everyone read access to the information.
Not general agreement that we need a requirements-specific tool; maybe can use a familiar format (e.g., Excel)
Caution: Form is as important as format when presenting this type of info to reviewers
Concern that people have already been pushed hard to document requirements and will not want to spend more time rewriting/reformatting them.
Amelia and I will assist as we can, but we all recognize it is a lot of work and will need to be shared
Suggestion to do it in steps; to start with high-level requirements (few people involved), then distribute them in new format to contributors of lower-level requirements. This way they (larger group of people) have example to follow and can see how theirs must fit in.
I still need to provide examples (at the bottom), so that folks can use this page as a reference
I will provide an Excel template within the next week.

More? (Yes, read on...)

-- Anne

Suggestions that would help accommodate CF requirements (from Tracy Lundin 2/15/11):

Need to list applicable codes and reports (AH: add object types for them)
Document source (originating person) (AH: add column)
Reference docdb # that relates to (gives rationale for) the requirement (AH: add column)
Make it a requirement that EITHER the "rationale" field OR the "docdb #" field be

Suggestions that would enhance the traceability of the verification process from Michael R. Campbell 2/11/11:

I suggest adding a name field in the verification section to identify the verifier.
Similar to the “object text” field, I suggest adding a “verification text” field where the verifier can make a clear verification statement, or point to a separate doc.

For example: If the requirement is “the primary beamline shall use conventional magnets”, then there is no verification test required, just a simple statement like “the primary beamline does use conventional magnets”.

But for a testable requirement such as “the primary beam vacuum pressure shall be less than or equal to 1x10-8 Torr”, there would definitely be testing and a final test report document. The test report could be checked into docDB. The verification text could simply say “Test passed. Ref doc # XXXX in LBNE docDB for test report”.

Goals of this meeting

Prepare you to redraft your requirements
Get your input on the current plan and see where to revise
Determine how we'll proceed, and agree to proceed!

Goals of this effort to re-document the requirements

Unify/standardize/clarify format and language of all objects in the objectives-requirements-design chain
Nail down requirements, organize them and distinguish them from other objects (e.g., assumptions, design parameters)
Nail down and illustrate traceback information
Simplify CDR (both production of and final product) based on clear requirement and design parameter documentation.
Satisfy reviewers, pass CD-1, and have good foundation for moving ahead to TDR stage.

Rough Plan (this should morph into a task list at some point)

Learn about "requirements engineering" -- (many variations on definition, here's one:) The process of establishing the services (or functions) that the customer (in our case, the scientists in the collaboration) requires from a system and the constraints under which it operates and is developed.
Evaluate and choose software tool to manage the requirements etc. information (DOORS, TeamCenter)
Collect information in form of Excel spreadsheet that will import nicely into management tool.
Figure out review strategy for information (maybe Jim already has one), and make sure it all gets reviewed properly
Determine the reports that will need to come out of it
Enter the spreadsheets into tool, set all the appropriate traceback links, and set a baseline.
Create reports
Review, revise, rebaseline if necessary.
Restructure CDR such that it pulls in and/or refers to this information. It should NOT contain copies of the information; this leads to duplication errors and confusion.

Types of objects to document and link between for traceback

Objective (three levels: primary, secondary and add'l secondary, according to Jim's doc 3056)
assumption (we need to make sure these are really assumptions, if they're requirements then list them as such)
basis for requirement (some requirements and design choices are based on results of previous experiments or budget constraints, etc. rather than physics goals; let's state the actual basis for each item)
constraint (these may take the form of schedule requirements or cost requirements, so we may or may not need a category like this)
requirement (lower down, let's discuss the categories of requirement to include)
design choice (e.g., membrane vs modular; it's not really a parameter, it's a choice)
design parameter

Requirement types (and explanations added 3/14/11)

physics: Physics req -- aka science req -- is a high-level req directly dictated by the physics objectives. E.g., "the FD shall be located between 1000 and ?? km from the neutrino source" (to optimize oscillation probabilities).
functional: A req on what the system must DO in order to function properly to meet the physics objectives; aka a "capability". E.g., "the cryostat shall hold at least 20kt of LAr."
interface: A requirement on a system/component that interfaces to the system being described. The current system depends on fulfillment of this requirement by the external system/component. E.g., a far detector may require that "the incident beam shall be above xyz kW in energy."
engineering: A requirement that affects engineering systems; it does not directly impact the functionality. E.g., "The cryostat walls shall insulate the tank such that a refrigeration system of only xyz capability is needed to maintain the contained argon below its boiling point."
performance: A non-functional requirement on a quality of the system/component in question, e.g., on availability, precision, response time, scalability, and so on.
logistical: A non-functional requirement on ancillary equipment, space or other item that allows construction or operations to proceed.
ES&H: A health or safety requirement following from ES&H standards.
other regulatory: A requirement following from (non ES&H) imposed government or facility standards.
cost: A requirement/limitation on costs; e.g., the total PMT cost shall not exceed $xyz, or shall not exceed xyz% of blah.
schedule: A requirement/limitation on time; e.g., "the total PMT installation shall not exceed xyz months," or "shall not begin until xyz is finished."

facility: Removed 3.14.11; this is now covered by "interface"

Metadata to store

Unique ID number (may have subproject prefix)
Creation/modify dates and by whom
Object heading
Object text
Type (objective, assumption, basis for requirement, constraint, requirement, design choice, design parameter)
Subtype (depends on type; e.g., for requirement: )
Rationale
Status (proposed, accepted, 'met and verified', obsolete, superseded)
Original ID
Associated WBS number
Verification method (analysis, demonstration, inspection, test for value)
Verified? (date)
Notes

Subtypes per type:

Objective: primary, secondary, additional secondary
Requirement: physics, functional, facility, performance, logistical, ES&H, other regulatory, cost, schedule
Constraint, Assumption: cost, schedule, science, technology, ES&H, regulatory, HR
Basis for requirement: previous measurement, other precedent, logistics, ES&H, regulatory
(I don't think design choices or parameters need subtypes)

Each requirement must be:

necessary, verifiable and attainable
clearly, unambiguously written
about one single issue (i.e., avoid "and”)
about what the 'system' needs to accomplish, not what a 'component' of it should do
NOT about implementation (the HOW), but rather about WHAT is needed. (test: ask yourself why the requirement is needed; if this leads to another requirement, it's probably an implementation statement)
NOT about operations (don't think about HOW you'll do something with the system, think of what the design needs to make possible for your tasks, and let the designer figure out how to design it)
specified to the appropriate level, considering function, cost, schedule, etc. Over-specification leads to $25k coffee pots (e.g., if triple redundancy is overkill, don’t specify it)
appropriately stringent (e.g., don't say "exactly 100 ft" if it can be 100 +/- 3 ft)

Standard terminology

Requirements use SHALL
Statements of fact use WILL
Goals use SHOULD
Requirements do NOT use: “is”, “was” and “must”
Requirements do NOT contain unverifiable words like “maximize”, “user-friendly”, “adequate”, and so on
Requirements NEVER contain: “but not limited to”, “etc.”, or “and/or”

Examples

coming in the spreadsheet I'm sending around; I can't believe this wiki doesn't let me upload xls documents...

Instructions for filling out Excel spreadsheet

Please follow the above guidelines for distinguishing the different types of objects, structuring requirements properly and for language to use.
Put headings and objects into hierarchical structure using "Object Level" column, e.g., 1 main heading --> 2 secondary heading --> ... --> n object. Use no more than 5 levels.
"Object Number" is for your own reference; it may help you to keep track of your requirements in the spreadsheet, but I will not pull it into a requirements management tool; they generate unique numbers.
For rows containing only headings, select "(label)" from the "Type" drop-down list.
For rows with objects, select the appropriate object "Type" from the list.
Some object types have subtypes; check the drop-down list in "Subtype" column to see. If there's a list, choose the right value.
Enter the Object Text according to the guidelines given.
"Orig ID" is optional; this may help you trace back to your old documents.
"Parent": Within Excel, we will document traceback by linking the object to its parent's "Object Text" cell.
To create a link:

Note the row number of the parent requirement, and copy the text of its "Object Heading".
Select the cell labeled "Parent" for the current (child) object.
Paste the copied text into it.
In the same cell, press Control-K (or right click and select Hyperlink). A dialogue box appears.
On PC, select "Place in this document" then in Cell Ref, enter the cell number (e.g., F12) of the parent Object Text (column is always F). On Mac, select "Document," click "Locate" and on the resulting popup, select the sheet and enter the cell number.
Click OK.

Every object must include at least one of the following: "Parent", "Rationale" or "Docdb ref" number.
"Source" is intended to identify the person who originated the requirement (or other object), but it could be a document reference or something else, if more appropriate.
Requirements must be verifiable (other object types don't need this). Choose from the drop-down list the method that best describes how verification will be done.
Also enter who will (or afterwards, "did") verify (the person, group, or institution, as appropriate), and any notes about the verification.
Enter last modified date (when it really changed last, i.e., if its text is significantly different from the original, put the new date).
Enter Status from the drop-down list.
If an object has the "Status" of "superseded", type the new object heading in "Notes" along with the reason.
Add notes as needed/desired.

Questions? Write to aheavey@fnal.gov.

Requirements-meeting-Feb11

Contents