Drasil: 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

• [x] GamePhys (#1321)
• [x] GlassBR (#1300)
• [x] NoPCM (#1282)
• [x] SSP (#1273)
• [x] SWHS (#1282)
• [x] Remove generated NFR intro from non-priority reqs (#1333)
• [x] Remove 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. :smile:

[samm82]

There was discussion on #1223 about how to best come up with the NFRs in a complete sense, but still not sure how to best go about this. I'll start with implementing SSP (based on the caseStudies) and go from there?

[bmaclach]

Your plan sounds good to me, @samm82. The impression I got was that getting the right text for stating each NFR is not a priority right now, we just want them to use the new format. @smiths, correct me if I misinterpreted that.

[smiths]

Yes, @bmaclach, you are correct. We should have the infrastructure in place so that each example can have a list of NFRs, but the content of those NFRs is not a priority. Adding a few placeholder NFRs, as you did for SWHS is a good idea.

[samm82]

https://github.com/JacquesCarette/Drasil/blob/2cf1aeb029a5ca7d02d0a5afebd2253a7a088129/code/drasil-docLang/Drasil/DocumentLanguage.hs#L200-L204

For now, I created a new NonFReqsSub'', which is awful, yes, but follows the FReqsSub structure for the sake of consistency. (I might be able to abstract this a bit more, but I'm still working on it.) I've added one "test" FR right now, and it seems to be displaying how we'd want it. However, I seem to be stepping on the toes of @bmaclach's work, and right now, the introductory sentence explaining the prioritization is missing (which I plan to add back in later by passing in a sentence to be added to the end of the intro). Before I go too far down this path, am I taking the correct approach? And how generalized should we make this intro sentence across the examples? @smiths @bmaclach I haven't gone too in-depth into the changes that have been made, but it seems like the end goal is to get the NFRs displaying like how the FRs are currently, and this seems like the best approach to do that.

Here is the sentence from caseStudies for reference: "SSP is intended to be an educational tool, therefore accuracy and performance speed are secondary program priorities. Instead, the following non-functional requirements are prioritized:"

EDIT:
I forgot about these functions that @bmaclach created 😬 I'll use them to generate the sentence to be displayed after the section intro.
https://github.com/JacquesCarette/Drasil/blob/1bf147eb59597e47ed7a119b489aeddea1b2973f/code/drasil-docLang/Drasil/Sections/Requirements.hs#L56-L57

https://github.com/JacquesCarette/Drasil/blob/1bf147eb59597e47ed7a119b489aeddea1b2973f/code/drasil-docLang/Drasil/Sections/Requirements.hs#L65-L69

https://github.com/JacquesCarette/Drasil/blob/1bf147eb59597e47ed7a119b489aeddea1b2973f/code/drasil-docLang/Drasil/Sections/Requirements.hs#L76-L79

[bmaclach]

I can't speak to all of your questions, but I can say that you are correct that my goal was "to get the NFRs displaying like how the FRs are currently". As long as you're not changing that, then you're not really stepping on my toes :)

The potential downside I see to NonFReqsSub'' is that the entire Contents of the section need to be defined in each example, whereas with NonFReqsSub' some of the construction of the Contents is automated in the DocLang. But I'm not sure how big of a deal that is.

[smiths]

I agree that how the NFRs are displayed should match how the FRs are displayed. The best way to code this is more the domain of @JacquesCarette. I do see a bit of a red flag with the comment by @bmaclach. In general, we want automation. If NonFReqsSub has more automation, then we don't want to lose that.

[samm82]

I think once again I've dived into a solution without thinking it through too much - I need to merge my solution (of using the FR pattern) with @bmaclach's (of automating the example sentence). I'm just working through the changes I've already made to find the cleanest way to do that.

EDIT: And by merging the two solutions, I mean (almost) completely erasing mine because I didn't understand @bmaclach's (😁 sorry).

[samm82]

Now that I've gotten things working, I've moved nonFuncReqF' to nfReqF to be consistent with how fReqF works for FRs (just an FYI @bmaclach)

[JacquesCarette]

Let's try to do a little bit more planning in the future. We need to properly understand the problem first, then a solution will likely be clear.

[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 2de462e8b 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. :smile: 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.

[samm82]

Should I make a new issue for adding this section @smiths? And who should I assign? EDIT: #1276

[smiths]

@samm82, yes, please create an issue for the new section. I think it makes sense to assign it to yourself. :smile:

[samm82]

I'm noticing that a lot of these NFRs (if not all) will be general (ie. the NFR for correctness won't really change between examples), and shouldn't be defined in any one example. Should they be defined in Data.Drasil.Concepts.Documentation or somewhere else? @JacquesCarette @smiths @bmaclach

[smiths]

The NFRs that are currently being written are just placeholders. That is why they are the same. They won't be the same when we actually spend some time to think about them. I'm sure there will be similarities in patterns, but we want to be able to write them separately for each example.

[samm82]

OK great - thanks for the clarification!

[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.) :smile:

[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.