Add scope, motivation, and software review information to generated software-READMEs #3248
Conversation
|
A few outstanding items (potential new Issues):
|
| @@ -1,4 +1,6 @@ | |||
| # DblPendulum | |||
| > The program documented here is called DblPendulum. | |||
There was a problem hiding this comment.
This text seems strange in a README file. The README file doesn't document DblPendulum. I feel like the README file would just start with the program name, possibly as a title (like #DblPendulum)
There was a problem hiding this comment.
You already have #DblPendulum. Do we need the sentence at all? If we need a sentence, I guess it might say something like "This program is named DblPendulum". (Seems redundant though.)
|
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. |
|
The change to the README file (to remove the part about "the program documented" here) looks good to me. |
| @@ -52,6 +52,8 @@ type CaseName = String | |||
| type ExamplePurpose = String | |||
| -- | Description of example | |||
| type ExampleDescr = String | |||
| -- | Motivation of example | |||
| type ExampleMotivation = String | |||
There was a problem hiding this comment.
this information that is quite specific to the README has really gotten too large to fit in Language.Drasil.Code.Imperative.GOOL.ClassInterface. This should be split out into its own file.
It doesn't even belong to Language.Drasil.Code.Imperative, as it is quite independent of that. Finding a better home needs a design.
| @@ -49,6 +49,12 @@ data CodeSpec where | |||
| purpose :: Purpose, | |||
| -- | Example Background. | |||
| background :: Background, | |||
| -- | Example Scope. | |||
There was a problem hiding this comment.
why are these all Example X? The data structure is a "Code Specification". It feels like there is a mismatch.
Futhermore, are we now requiring all this information for all codes?
There was a problem hiding this comment.
My guess is that these were meant to specify that it is the purpose, etc., of the example itself, but I think this is a bit redundant
There was a problem hiding this comment.
Maybe CodeSpec just needs to carry a reference to the SystemInformation it was constructed for? Right now, these fields are carried in both, and CodeSpecs are always a clone of SystemInformations manually created ones.
| @@ -104,6 +104,9 @@ si = SI { | |||
| _authors = [naveen], | |||
| _purpose = [], | |||
| _background = [], | |||
| _motivation = [], | |||
There was a problem hiding this comment.
Reviewing multiple examples in a row that all set these 3 things to be empty. This really does start to feel like a hack. If we're going to implement a feature, shouldn't we be using it in all the examples? Just using it in Projectile does not convince me that this is a feature that is implemented at the right level.
There was a problem hiding this comment.
We do have a form of this information that we write for the SRS documents, as we just recently did for #3777. It would be nice if we could share them with a chunk that defines what the purpose, background, and motivation of each case study, respectively, is.
This is also related to #3773. The specific purpose, background, and motivation of each case study are just instances of the generic concepts of purpose, background, and motivation. In other words, for our current design, these might just be unique ConceptInstances for each case study. Rather than having lists here, it might be that we just have a UID to the specific ConceptInstance.
There was a problem hiding this comment.
Well, actually, would it be nice to share the same SRS discussion of the purp., back., and moti. in the generated READMEs? I'm not sure anymore. We might want a longer version of that in the SRS, and a shorter one here. @smiths do you have any thoughts on this? Do you think we can share them?
There was a problem hiding this comment.
@balacij I think for every example we should be able (if we haven't already) to write a one sentence purpose. This one sentence purpose would fit nicely in the README. It should also be usable in the SRS. As @NoahCardoso recently did, we can reuse the purpose in the Introduction to the SRS. Although we haven't done it yet, I could see us wanting to have a longer version of the purpose for the SRS. For instance, our one sentence purpose could be something like:
The software library provides a multi-domain Lattice Boltzmann solver.
(I'm working on a project with a colleague in mechanical engineering that could be described with that sentence.) The problem with this one sentence purpose is that it introduces at least two concepts that not everyone will be familiar with. This could be fine in a README file, but in the SRS, a description of what multi-domain means and what Lattice Boltzmann means would be in order. Following #3773, we could say that the purpose is an idea definition that includes two other idea definitions. In the README we might not generate the text for the definitions of the sub-ideas, but for the SRS, this would be a natural thing to do.
We could go through a similar conversation for Motivation and Scope. I think Motivation would be fairly simple, but Scope does get more involved. There are different views of Scope. There is a simple "high level" view, and then there is the view that decomposes the Scope into Scope Decisions (things that are entirely left out) and Assumptions. The Scope can also include typical values and examples.
|
I wonder if this PR is related to #3430 at all (for example, in its capturing of motivation). |
It looks like different values of sections in the README aren't being formatted correctly; related to #3256
|
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 |
|
Yes, it is tangentially related to #3430 in that the larger topic is "what should be in an introduction?" |
|
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" |
|
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? |
|
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. |
|
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? |
|
I think this PR has a related goal, but is otherwise independent from my work with Prior to my work, This PR introduces new fields for "motivation", "scope", and "software review" into |
|
So does it seem worth resurrecting, or is it not worth it in its current state (so we should close it)? |
|
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 |
|
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
changed the title
| > Motivation: Projectile motion is a common problem in physics. | ||
|
|
||
| ------------------------------------------------------------ | ||
| ## What | ||
| Common examples of projectile motion include ballistics problems (missiles and bullets) and the flight of the balls in various sports (baseball, golf, football, etc.). |
There was a problem hiding this comment.
When I think of "motivation" related to software, I think that I think (lol) of strictly technical features:
- What makes this software special?
- What differentiates this software from other, similar, software?
However, this (the linked code) answers the question of "what is the motivation of the problem this software somehow solves?," which I think is more intended for a non-technical audience. So, I'm not quite sure who our audience is for this information (technical/non-technical/mix?).
If a software (assuming it were publicly available) is large/prominent enough such that it would have this kind of information, I imagine it would have a website, where this kind of marketing material would be found instead. Conversely, if the software isn't, then I imagine it would be somewhat self-evident to the audience of developers seeking out the software (they probably have a specific issue in mind, searching for a few specific keywords, and then looking at program/library documentation). If it's somewhere in the middle, it might, but I would think the non-technical discussion would remain in a "Who is this software for?" or as part of a "What can X do?" section that highlights features. It might just be that we need to rename the headings and/or move it around, that is.
There was a problem hiding this comment.
Addendum to this after my latest comment below: the answers to (1) and (2) in a motivation section would be terse (e.g., X was too slow / A goes fast, Y is purely CLI-based / A creates a pretty GUI, Z is... / A has..., etc.), so it would not be as complete as the potential "Software Review"/Comparison Chart.
There was a problem hiding this comment.
These could potentially be even more terse;
A solves various problems with the following alternatives: X is too slow, Y is purely CLI-based (while A creates a pretty GUI), .…
By formatting it this way, we have the flexibility to comment on A's functionality/qualities when necessary for clarity/context, but don't need to when it is redundant (although this completeness might be desired); a table may also be a nice way of formatting this data.
There was a problem hiding this comment.
Yep, that's better. Though, I think the more complete, less marketing-like version, is reserved for the "Software Review" / Comparison Chart, but I agree with you. I think a good example of what we're talking about here is the Gitea project, where, in their README.md, they give very quick highlights in the Purpose, and then have a dedicated page for software comparison.
There was a problem hiding this comment.
If the bar for the motivation is to do something better than the competition, than none of our case study projects have a motivation. 😄 Research and commercial projects should have the kind of motivation that distinguished the project from the "competition." Although our software doesn't have this kind of motivation, since it doesn't do anything better than the competition, I still think we can motivate it. Of course we have the motivation for our Drasil research project, but that isn't the motivation I'm thinking. The motivation is for why have software to solve the kind of problems the software solves. It isn't motivation for why the current software is the best, but rather the motivation for having software to solve the problem. Projectile motion is an important physics problem. A software tool to help with projectile motion will help physicists/engineers/scientists.
If we had enough examples, either real or brainstormed, we could identify the patterns in the Motivation statements and build a language for generating motivation statements. For now, I think I'm fine with a non-parameterized statement that we make for each example.
There was a problem hiding this comment.
You've convinced me 😄
A software tool to help with projectile motion will help physicists/engineers/scientists.
Do you think we can replace the existing "What" section with your quote (or a variation of it)?
There was a problem hiding this comment.
Yes, this does sound like a better "What". I do think we also need examples, but probably not in the README file. I think of the examples as more something that goes in the SRS to help define the scope. In projectile motion if the scope is for velocities less than those for ballistics, we can use the example of the speed of the balls in various sports. The example and the scope are related. They are also related to assumptions and typical values. I don't think this information belongs in the README; I just mention it as I sort out my thoughts on the matter. 😄
|
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). |
balacij
changed the title
Contributes to #3159