Updated NFR for maintainability to refer to code, not SRS: #3288

[BilalM04]

Updated the NFR for maintainability to the following description:

If a likely change is made to the finished software, it will take 10% of the original development time, assuming the same development resources are available.

Change applied to the following examples:

• GamePhysics
• GlassBR
• NoPCM
• PDController
• Projectile
• SSP
• SWHS

TO DO: Instead of hard-coding the "10%", it should be a parameter than can vary at the time of SRS generation.

closes #3288

[smiths]

I agree with the feedback from @samm82, including that the word percent shouldn't be there and the percentage symbol should not be in italics. Those changes will make the change fine from the point of view of stable. How the changes are done should also be investigated. Specifically, we don't want the same Drasil code repeated.

[BilalM04]

@samm82 @smiths

It seems the "%" symbol is always generated between an <em></em> tag in HTML, which by default renders the contained text in italics. The issue is currently present in the existing SRS documents, for example in the Input Data Constraints table in the SRS for Projectile.

In regards to the code duplication, I am unsure where to define the requirement so it can be accessed by various examples. Currently, it appears that requirements are defined for each example, with no place for "common" requirements. One possible module I was looking at is code/drasil-docLang/lib/Drasil/Sections/Requirements.hs which has the following description in its README:

Contains the functions to generate the Requirements section

[smiths]

@samm82 @smiths

It seems the "%" symbol is always generated between an \<em\>\</em\> tag in HTML, which by default renders the contained text in italics. The issue is currently present in the existing SRS documents, for example in the Input Data Constraints table in the SRS for Projectile.

The percent symbol isn't a priority. We can leave it as it is for now.

In regards to the code duplication, I am unsure where to define the requirement so it can be accessed by various examples. Currently, it appears that requirements are defined for each example, with no place for "common" requirements. One possible module I was looking at is code/drasil-docLang/lib/Drasil/Sections/Requirements.hs which has the following description in its README:

Contains the functions to generate the Requirements section

@samm82 or @balacij can likely point you to the best way to add common requirements. Much of the boilerplate in the requirements documents are shared between examples. @samm82 was working on a way to standardize common requirements, like the input and output requirements. Ideally the structure of the requirements will be the same between examples, but they will be parametrized by the percentage of time needed for the change, so that different examples can have different percentages. There really isn't a compelling reason for a specific value for any of our examples, but in general not every future maintainability requirement is going to be identical.

[JacquesCarette]

• percent in italics should be made into a separate issue. It's likely bound up with other issues, so that changing that might not be so easy
• hopefully you've had the functions that deal with boilerplate pointed out to you (offline). They definitely exist!

[balacij]

One possible module I was looking at is code/drasil-docLang/lib/Drasil/Sections/Requirements.hs which has the following description in its README:

Looking at the contents of that file, I think you've found a good spot, @BilalM04.

Aside: in that file, I don't quite like how reqIntroStart and the likes are used -- it de-duplicates Sentences, but not the generic shape of the section introductions. There should be a single "generic section introduction builder" that contains those strings and a list of "contents" in the section that are added to the generic section introduction as needed.

[balacij]

Certainly cleans up the code nicely 😄

[JacquesCarette]

Up to @balacij to verify that the changes he'd asked for have been done.