Use new Non-Functional Requirement format in examples

[bmaclach]

All of the examples should be updated to use the new Non-Functional Requirements list-format discussed in #1223.

TODO

• GamePhys (Fixed Requirements in GamePhysics #1321)
• GlassBR ([Small PR] GlassBR Nonfunctional Requirements #1300)
• NoPCM (Requirements in SWHS and NoPCM #1282)
• SSP (Transitioned NFR implementation in SSP #1273)
• SWHS (Requirements in SWHS and NoPCM #1282)
• Remove generated NFR intro from non-priority reqs (Removed old NFR Code #1333)
• Remove old NFR code (Removed old NFR Code #1333)

[smiths]

@bmaclach, please hold off on completing this issue. It seems like a great issue to assign to @danscime or @samm82 to ease them back into Drasil. :-) I'll verify this with @JacquesCarette before we assign anyone issues, but I'm sure @danscime and @samm82 will appreciate having tasks to keep them busy. 😄

[samm82]

In caseStudies, the first NFR refers to a section that doesn't exist in Drasil.

Also, since properties of a correct solution aren't applicable for SSP, should they be removed from this NFR, or should some be added (either to caseStudies and/or Drasil)? @smiths @bmaclach

In 2de462e I used a placeholder string (and a FIXME) for now.

[bmaclach]

I remember @smiths and I agreeing that that section was not applicable to SSP. Your placeholder text is probably fine for now though, since we plan on rehauling how we describe these requirements at some point in the future. @smiths can confim.

[smiths]

@bmaclach and @samm82, the properties of a correct solution section for SSP isn't technically "not applicable". We just couldn't come up with any. 😄 We definitely want to keep the section, since it is part of the template. At some point we might also realize that we have forgotten or missed a property.

As far as the NFRs go, we can think of them as placeholders for now. Including a FIXME is a good idea. What I would really like for the correctness NFR should really (eventually) point toward the verification and validation report (which isn't currently part of Drasil.)

[bmaclach]

That section actually doesn't exist in Drasil for SSP. I inadvertently skipped over it when going through the SRS and porting changes. It can be easily added, though.

[JacquesCarette]

I would have said things differently. I think a bunch of NFRs, just like FRs, will be generic. The more interesting ones will be generic-but-specializable. But that's definitely something down the road.

[smiths]

@JacquesCarette, I think we agree more than we disagree on this. There will be significant overlap between examples on the NFRs; the main differences will be in the details. It is these differences that will make the examples interesting. The main thing at this time is that we agree that, for the moment, we should have other priorities. We can circle back to NFRs in the future.

[samm82]

The current intro to Chipmunk's NFR section generated by Drasil is:

Games are resource intensive, so performance is not a priority.

While in caseStudies, it is:

Games are resource-intensive, so performance is a high priority.

So I'm going to have to modify the way these introductions are generated. (I'm just documenting it here)

[smiths]

Thanks for noticing this @samm82. The case study has the correct NFR statement.

[samm82]

@smiths I also used the NFRs from stable for now, not from caseStudies - which ones should I use? caseStudies has performance and usability (and reusability, but I added it to Drasil anyways because other examples used it), but not portability or reliability.

[samm82]

@smiths @JacquesCarette For changing the intro to the NFR section, should I create another section constructor that would take a list of high priority requirements (instead of no priority reqs), or add a parameter to the constructor that would indicate the priority of the list of "extra" requirements passed to it?

[JacquesCarette]

This is a 'semantic' question -- i.e. what meaning are we trying to communicate here. I think @smiths has to figure that part out, then we can figure out how to encode that knowledge into Drasil.

[smiths]

@samm82, including the priority is a good long term idea, but I think it is premature to worry about it at this stage. The NFRs are really a placeholder right now. Higher priorities are the functional requirements, design, code generation, and testing. My thinking is that the priority of the NFRs will be indicated using a ranking based on the Analytic Hierarchy Process (AHP), which involves pair wise comparisons between all of the NFRs. This would take more thinking and planning than we currently have time for.

[samm82]

@smiths So should we just let the intro be wrong for now, since the section is essentially a placeholder anyways?

[smiths]

@samm82, what is wrong with the introduction? (I haven't read it in a while.) 😄

[samm82]

From a comment above:

The current intro to Chipmunk's NFR section generated by Drasil is:

Games are resource intensive, so performance is not a priority.

While in caseStudies, it is:

Games are resource-intensive, so performance is a high priority.

So I'm going to have to modify the way these introductions are generated. (I'm just documenting it here)

The way the intros are generated are by passing in a list of non-priority requirements, which are highlighted in the intro. However, in GamePhysics, performance is passed in, although it is a high priority requirement, not a non-priority one. This means it is referenced in the same way as a non-priority req, which is wrong. So either we add a new constructor to build from high prioriyu reqs, or we add another field for high priority reqs to the existing constructor. Alternatively, we could just leave it, since we will be revisiting the NFRs anyways.

[smiths]

Thank you @samm82. Please remove the reference to priority from this example (and any others where it occurs). All of the NFRs in each of the examples are important; we really don't have a relative ranking at this point. That was just filler text. Since the filler text is confusing, it is better if we don't have it.

[samm82]

Just so I'm 100% clear, we should remove this NFR intro line entirely, including in examples like GlassBR:

This problem is small in size and relatively simple, so performance is not a priority. Any reasonable implementation will be very quick and use minimal storage. Rather than performance, the non-functional requirement priorities are:

[smiths]

Yes, remove all of the text you listed, except for "The non-functional priorities are:"

[samm82]

For consistency, I think that last line should also be removed, since a similar line doesn't appear for the FRs and this sentence comes before this generated intro:

This section provides the non-functional requirements, the qualities that the software is expected to exhibit.

[smiths]

Sounds good. I agree.

[samm82]

Should I remove the old code for generating the intro, or should I comment it out in case we want to use it in the future?

[smiths]

As far as removing old code does, I think you can safely delete it, but @JacquesCarette really should weigh in on this.

[samm82]

I think I'll just comment it out for now until I get the go-ahead, just so I can get a PR open.

[JacquesCarette]

Dead code should be removed. There is nothing particularly 'valuable' in that code.