Fill purpose fields of all SystemInformations

[hrzhuang]

The purpose field in SystemInformation is newly added and currently empty for all of our examples. #3390 has a discussion by @smiths explaining that the purpose information is mostly found elsewhere in the documents and that same information can be used to fill in the purpose information.

[hrzhuang]

@smiths currently in our examples we have a "problem description." For example, for GlassBR this is "efficiently and correctly predict whether a glass slab can withstand a blast under given conditions." Should this be used as the purpose?

I'm also looking into #3218 where we want to use the problem description for the \brief. The problem here is that currently the problem description is only in the SRS and is not made available to the code generator, so it would be nice if it was included in SystemInformation somehow. Should this be a separate issue?

[smiths]

@hrzhuang the problem description for GlassBR would be good wording for the purpose. Is the problem description a chunk of information in the document, or just a string? If there is already a chunk of information called "problem description" for each example, then we probably don't need a synonym called purpose. Actually, I like the name purpose better than "problem description", but that would be a separate conversation. I'd first like to know whether problem description is "codified" in the examples, in the way that we are proposing to codify purpose.

With respect to using problem description for brief, I believe this is why we added purpose in SystemInformation.

I think I remember now. I think the plan was to capture purpose in System Information and then use it to generate the problem description and to fill in \brief. The purpose will likely appear in other places as well, once it is available to all artifacts.

[hrzhuang]

The problem description is a Sentence. I think it's called "problem description" because it's currently only used for the "problem description" section of the SRS.

[smiths]

@hrzhuang would it be feasible to define the purpose in SystemInformation and then generate the "problem description" in the SRS from that? As a first approximation, the purpose field could have identical text to the "problem description." Unless the problem description example from GlassBR is atypical. If the problem description is longer in the other examples, then we'll need to distill a purpose from the problem description. The purpose should be one short phrase that captures what the software is trying to accomplish. It is like a more abstract version of the goal statement(s).

[hrzhuang]

Yes, I think that would work. All of the problem descriptions are short with the exception of the one for game physics.

Also, for future reference, what I've been referring to as "problem description" is more correctly the introduction to the "problem description" section of the SRS. The section contains more than just the short introduction.

[smiths]

That sounds good @hrzhuang. Let's start with the purpose statement being lifted from the problem description and then used to generate the problem description, and other things. I think if we study the problem descriptions we'll find other nuggets of information that can be extracted and codified, and then used to generate the problem description. That can be something we do on a subsequent pass though. For now, we can focus on the purpose.

[hrzhuang]

I submitted a pull request that lifts purpose from the existing introductions of the Problem Description sections. I mention this in the pull request but I will repeat here: Template and HGHC are excluded from this since they do not have a Problem Description section, and Game Physics is excluded since the introduction of its Problem Description section is too long. Should we create separate issues to fill in the purpose for these examples?

[samm82]

Since the Template and HGHC examples are meant to be small and bare-bones, they shouldn't really have the Problem Description section. Just make a separate issue for GamePhysics and then close this issue 😁

[hrzhuang]

Got it. I opened #3419. Closing this one now.