Add scope, motivation, and software review information to generated software-READMEs

[peter-michalski]

Contributes to #3159

[peter-michalski]

A few outstanding items (potential new Issues):

1. Goal Sentences are capitalized and do not render nicely in the README. I'm wondering if Sentences in Drasil should instead be lowercase (in situations like ConceptInstance definitions) and a function could capitalize them near their final targets. This may make working with them easier.
2. I'm wondering if annotations like purpose, background, motivation, should become a chunk.

[smiths]

With respect to your potential issues @peter-michalski, my instinct is that sentences shouldn't be capitalized so that we can put them together in different combinations. We can capitalize as needed. This reminds me of the "extra the" issue (#3234). We can reduce some problems by keeping the sentence information we codify simple.

[smiths]

The change to the README file (to remove the part about "the program documented" here) looks good to me.

[samm82]

I wonder if this PR is related to #3430 at all (for example, in its capturing of motivation).

[samm82]

As mentioned in the commit for the merge, there seems to be an issue rendering the purpose correctly; compare:

> Purpose: efficiently and correctly predict whether a launched projectile hits its target

> Motivation: Projectile motion is a common problem in physics.

This is related to #3256

[JacquesCarette]

Yes, it is tangentially related to #3430 in that the larger topic is "what should be in an introduction?"

[smiths]

I don't know if this is the best spot for this comment, but looking at the Purpose for Projectile I wonder if we should remove "efficiently and correctly"? The purpose for Projectile is given as:

"efficiently and correctly predict whether a launched projectile hits its target"

Our SRS doesn't define what we mean by efficient. Our code doesn't do anything (that I'm aware of) to be efficient. Projectile is so simple that the notion of efficiency isn't really that relevant. Even if it was a more complex problem, we really haven't been focusing on efficiency. Our first goal for Drasil code has been correctness.

I don't think we need to specifically say our purpose is to "correctly predict". It seems obvious that we wouldn't consider a prediction that was incorrect as valid. Does it really need to be made explicit?

If we distill the purpose to its essential elements, we have:

"Predict whether a launched projectile hits its target"

[JacquesCarette]

The question remains: are there useful things in this PR (not in the abstract - we know this goes in a positive direction - but in the concrete code) that ought to be adapted and merged in?

[smiths]

I feel like the recent work that @hrzhuang has been doing with the "purpose" chunk of knowledge supersedes the work on this PR. There are already conflicts with the README.md files, and I think the current (main branch) versions are closer to what we want. Having said that, I'm just looking at stable. There may be something in the Drasil code changes that is useful to us. Someone else will have to comment on that.

[JacquesCarette]

Indeed, given @hrzhuang 's recent work this might be moot. Ricky, could you take a serious look at the original issue and the PR and see?

[hrzhuang]

I think this PR has a related goal, but is otherwise independent from my work with purpose.

Prior to my work, purpose already existed in SystemInformation, but it was not filled in for most of the examples. My work was extracting a purpose from the SRS, put it into the SystemInformation, then have the SRS pull that information from SystemInformation.

This PR introduces new fields for "motivation", "scope", and "software review" into SystemInformation, and they are mostly still blank except for the motivation of Projectile. So it is laying the groundwork similar to the introduction of purpose before I actually filled it in.

[JacquesCarette]

So does it seem worth resurrecting, or is it not worth it in its current state (so we should close it)?

[hrzhuang]

It doesn't seem too difficult to bring this up to date. I think it's really a matter of do we want the "motivation", "scope", and "software review" in SystemInformation and in the README files.

[smiths]

I like the idea of having motivation and scope available for the README file, and possibly other artifacts besides the SRS. Whether System Information is the best place for this information is a question for @JacquesCarette. I'm not sure what "software review" refers to.

[balacij]

In all honesty, I thought that "software review" was just a typo, and that "software revision" was intended.

Actually, it looks like it was intended to be "software review" and that "software review" means a comparison chart between a software (related to a README.md) and related projects. I think that "Comparison" is more appropriate, but I also don't really think this is something feasible for us to generate -- it would require an immense amount of knowledge of related popular software, and software qualities between our generated code and theirs (maintaining this does not sound feasible).