Non-functional requirements format

[bmaclach]

In Drasil, non-functional requirements are listed out in a single sentence, like so:

In the manual version of SSP, I changed this to a more formal list with more description:

Is the current Drasil behaviour enough, or is the more descriptive list preferred? The way Drasil renders non-functional requirements is common between all of the examples, so if we change it the change will need to be propagated to the rest of the examples, not just SSP.

[smiths]

@bmaclach, I definitely like the idea of breaking down the nonfunctional requirements into separate requirements. It was never the long-term intention to just use one sentence to summarize the NFRs. We did that because the NFRs were not initially a priority, and we had enough to do with the FRs.

I like the idea of adding separate NFRs, but I don't really like your specific examples, since they aren't abstract. You say how to achieve usability, not what it means to be usable. The challenge is that stating NFRs in the right way is far from easy. That is why we keep "punting" it to the future.

In the long run, I would like to see the NFRs expanded into considerably more information. We might want to explore the Volere templates notion of "fit criterion." For instance, for usability, the requirement could be an experiment, or survey that measures usability. Alternatively, it could be a count of the number of interactions (mouse clicks, keys pressed, etc) to get a given task done. I'm sure with some HCI research some other metrics could be devised.

There starts to be overlap with the verification and validation plan, which is another document that Drasil knows nothing about.

My thinking is that it would be nice to do something now with NFRs, but it still isn't time to really delve into how best to state them and measure them. That would be a bigger task than we currently have time to tackle. How much work would it be to add NFRs along the lines of what you described? That is, to have separate NFRs, with each one having its own text? That would give us a starting point for the future when we decide to really think deeply about the content of the NFRs.

[bmaclach]

@smiths I don't know exactly what to do to set up a more formal list of NFRs, but I have a general idea, and there are plenty of other examples of lists (like the functional requirement list) that I can use as a reference. So I would be surprised if setting up the infrastructure for this took more than a few hours. Seems reasonable to add this to my to-do list.

[Mornix]

Implementation wise, this should be similar to #1215. I believe all the infrastructure is there. All that should be needed (or it may already exist!) is a nonFuncReqDom (or similar) for ConceptInstance.

[bmaclach]

Thanks @Mornix. Reassigning this to myself to implement.

[smiths]

Sounds like a good plan to implement NFRs the same as the FRs. How best to state the NFRs can be a task that is investigated outside of Drasil.

[bmaclach]

Set-up for the new format for NFR's was merged with #1225. Created new issue #1229 for updating each example, so this issue can be closed.

[samm82]

@bmaclach Did you define an intro sentence for the nonfunc reqs somewhere in docLang (like the one for the func reqs)?

[bmaclach]

The intro paragraph (it's actually multiple sentences, my bad for saying "sentence" before) is built from 2 Sentences which are passed to the NonFReqsSub' constructor. Specifically, these functions put them together:

Drasil/code/drasil-docLang/Drasil/Sections/Requirements.hs

Lines 56 to 57 in 1bf147e

	nonFuncReq' :: [Sentence] -> [Contents] -> Sentence -> Sentence -> Contents
	nonFuncReq' noPriority priority_ reason_ explanation_ = mkParagraph $ reason_ `sC` (listO' explanation_ noPriority priority_)

Drasil/code/drasil-docLang/Drasil/Sections/Requirements.hs

Lines 65 to 69 in 1bf147e

	listO' :: Sentence -> [Sentence] -> [Contents] -> Sentence
	listO' explanation_ [] [] = S "so there are no" +:+ (plural priority) +:+ explanation_
	listO' explanation_ [] priority_ = S "so all" +:+ (plural nonfunctionalRequirement) +:+ S "are given equal" +:+ phrase priority +:+ explanation_ +:+ S "The" +:+. listT' priority_
	listO' explanation_ [s] priority_ = S "so" +:+ s +:+ S "is not a" +:+. phrase priority +:+ explanation_ +:+ S "Rather than" +:+ s `sC` S "the" +:+. listT' priority_
	listO' explanation_ s priority_ = S "so" +:+ foldlList Comma List s +:+ S "are not" +:+. (plural priority) +:+ explanation_ +:+ S "Rather, the" +:+. listT' priority_

Drasil/code/drasil-docLang/Drasil/Sections/Requirements.hs

Lines 76 to 79 in 1bf147e

	listT' :: [Contents] -> Sentence
	listT' [] = (phrase program) +:+ S "does not possess a" +:+ (phrase priority) +:+ (phrase nonfunctionalRequirement)
	listT' [_] = (phrase nonfunctionalRequirement) +:+ (phrase priority) +:+ S "is:"
	listT' _ = (phrase nonfunctionalRequirement) +:+ (plural priority) +:+ S "are:"

[samm82]

Great! Works like a charm (once I figured out how it was working 😂)