Expanding generated README content

[peter-michalski]

A subset of the following information is currently generated in each example's src README files:

• Example name
• Authors
• Making Examples
  • How to run and build the program
• Configuration Files
  • Lists required config files
• Version
• Unsupported Operating Systems
• External Libraries
• Blurb mentioning Drasil
• Copyright information and license link

Considering expanding what information is generated in these files, Categorizing the Content of GitHub README Files suggested by @smiths lists some common README file information based on a study of GitHub repos. I have also reviewed some GitHub repos dedicated to sample README templates. I have combined the suggestions from the paper and the repos into one file. There is considerable overlap. The paper does break down frequency of sections and information quite nicely.

Some common README file information:

• What
  • introduction, project background, features, stack
• Why
  • advantages of the project, comparison with related work
• How
  • getting started, how to run, installation, how update, configs, setup, reqs, depends, languages, platforms, demo, downloads, error and bugs, run tests
• When
  • project status, versions, project plans, road-map
• Who
  • project team, community, mailing lists, contact, acknowledgement, license, code of conduct
• References
  • API docs, get support, feedback, more info, translations, related projects
• Contribution
  • contribution guidelines
• Other
  • future features
  • support project
  • FAQ

The remainder of this issue will add justification for why some of the information commonly found in README files should or should not be generated with our examples. Once the updated README file content is decided, another issue can be created to investigate how to encode the information. Some of the information could already be specified in the examples.

[peter-michalski]

Information that should be part of the README files:

What:

• According to Prana et al. this type of content is commonly found in README files. The example src README files that are currently generated in Drasil do not have any of this information. Introduction and project background information should be generated in these files to document what the source code is actually for. The reason that this information should be added here is that the source code may be separated from other artifacts that explain the project. This information can be duplicated from existing example information.
• The blurb mentioning Drasil is appropriate.

Why:

• According to Prana et al., this type of content is not commonly found in README files.
• Information regarding advantages of the project could be added into the background information section above. This type of information in SC research software should be similar to the project background information.
• I'm not sure if information about related work would be appropriate to add into these files. This kind of information would be more appropriate in documentation artifacts than source code artifacts.

How:

• According to Prana et al., this type of content is commonly found in README files.
• Information on how to build/run the program is already generated in the file
• Installation information is not needed for these programs.
• Information on updates will not be needed.
• Parameter update information may be needed.
• Dependencies (language versions or external libraries) are already generated in the file. The generation of dependency information is appropriate.
• Platforms: unsupported OS's are already listed in DblPendulum

When:

• According to Prana et al., this type of content is not commonly found in README files.
• A blurb about project status would be a good idea to add.
• Version information should be added.
• Project plan and road-map information is better suited for documentation artifacts.

Who:

• According to Prana et al., this type of content is found in about half of README files.
• The project authors are already listed.
• It would be helpful to allow authors to add contact information to the README files.
• An option for acknowledgements is worth considering.
• License and copyright information is already listed.
• The other "Who" items are probably not needed in these files. Codes of conduct, mailing lists, community information fits into larger projects

References:

• According to Prana et al., this type of content is found in about half of README files.
• API documentation information is likely not needed for such research code.
• Support and feedback information is not needed for smaller projects. Contact information for developers would suffice.
• Related projects and additional information can be found in documentation artifacts, not code README files.

Contribution:

• Contribution guidelines should be part of documentation artifacts. Contact information for developers would suffice in the README.

Other:

• Future features information can be found in documentation artifacts.
• FAQ information is also better suited for documentation artifacts, unless specific to the code and language. In which case it is probably best placed in "How" type of information.

[smiths]

Thank you @peter-michalski. Great summary.

During our last Drasil meeting (#3184) I mentioned that I was going through the generated code for the Projectile example. I also noticed the absence of the "what" information. In the README file for Projectile we never actually say what Projectile does.

@peter-michalski, can you please look into what would be involved in adding "what" to our generated README files. We have the "what" information in the SRS, but it is unclear if it is easily separated from the other information in the SRS.

For the license information you are correct that we already generate it in the example README files, but as far as I know we only allow for one choice of license. That isn't a very Drasil approach. 😄 It would be nice if we let the users select their license.

For code of conduct, we could also offer the option of selecting from currently available codes, without having to generate our own.

Some of the information in the Prana et al README files can also appear in different documents. For instance, if we wanted to include contributing information, this could be in a separate CONTRIBUTING file. With the Drasil approach, the user should be able to specify where they want the information to appear.

[JacquesCarette]

This is indeed great. It also kick-starts something that I've thought about in the past: the concept of a "project" (not the best word, I'd like to find a better one); I think of Projective, but also Drasil, as a project. This is higher-level than the SRS. I think this is what SystemInformation was heading towards, but that too was too low-level!

A lot of the information above is both about the 'project' and the software. Some of the information should likely be in the SRS as well as the README.

Every single concept mentioned in both of @peter-michalski 's descriptions deserves a proper analysis!

[peter-michalski]

A comment in CreateMd.hs suggests how to add a Purpose section in the generated README files. It also points to #2224, which indicates that there used to be a Purpose section, but it was removed. Am I right to assume that this deprecated Purpose section held information that should be in a What section?

#2195, linked from #2224, sounds like the above from @JacquesCarette. It appears that we are circling back to that issue here.

I can add a separate What section (and other sections) to the generated README files now (after tinkering a bit with example specific information) using SystemInformation, so that these files convey important information that is missing. I can then proceed to try to pull SystemInformation apart (apart from SRS anyway), this may require some time to conceptualize first of course. There is a lot of information in #2195 to consider.

[smiths]

Maybe I'm not looking into this deeply enough, but I think it may have just been the heading purpose that was removed. I don't think we generated content for this section in the README. @peter-michalski, you may want to look deeper into the code history to see if I'm wrong about that.

If it isn't too much work, I would be fine with hacking together a purpose section for the README based on SystemInformation. I know that SystemInformation needs to be rethought, but it might help us see how to fix SystemInformation if we see how the information in SystemInformation is used, especially how the information is used outside of the SRS.

[JacquesCarette]

Yes, that's right, it's just the header that was removed.

Figuring out what such a purpose section should actually contain, and adding it in now (even if it's hacked in a little) does sound like a good idea.

[peter-michalski]

Prana et al. chose to classify the 'purpose' of a project under the 'Why' category. Regarding the inclusion of 'purpose' in READEME files, they note that

• "including information on the purpose of a project is a way for repository owners to differentiate their work from that of
  others"
• "describes the purpose of the project and motivates the need for it"
• "many README files lack information regarding the purpose and status of a repository"

Despite 'purpose' information being rare in README files, according to their study, we certainly can add this information back into our generated README files. Looking at Projectile's SRS, the first paragraph of the introduction section appears to have information we can reuse in the README for this purpose. It notes why it is useful to have such a projectile motion program. Information from the Problem Description section could also apply here although it could also be used in the 'What' section.

For the 'What' section, we could reuse information from the SSD section of the SRS, namely from Problem Description and Goal Statements, as well as from the Functional Requirements. This would cover the program introduction, as well as its inputs and outputs. The version information and blurb about Drasil also fall under the 'What' section according to Prana et al., but I think that their current location in the README file is adequate and should be left as is.

Of course this approach might not be appropriate with our other examples.

[smiths]

The information from Prana et al is definitely useful, but we don't have to follow their recommendations exactly. I think the purpose is just what the software does. The purpose is a brief abstract statement that characterizes what the software does. The other chunks of information that Prana et al mention should also be captured, and possibly even be documented in a "purpose" section, but we should keep our purpose as atomic as possible. Based on what @peter-michalski wrote above, the other chunks of information that we can capture include:

• a software review that compares and contrasts the existing work with related software. I didn't include the word differentiate in my characterization of the knowledge, because some software might be the same, or very similar, to other software.
• motivation for the need for the software

The Introduction of the SRS doesn't really say the purpose of the Projectile program. The information given, like "Projectile motion is a common problem in physics" isn't the purpose of the projectile program, it is more in the category of motivation or background. The purpose is currently given in the last sentence of the scope section: "Given the appropriate inputs, Projectile determines if the projectile hits the target." (I think it should be rephrased to "Given the appropriate inputs, Projectile determines if the projectile hits a given target.")

I actually don't like the purpose showing up in the scope. The purpose being the last sentence of the introduction would be a better fit.

Looking at the SRS, the separate pieces (chunks?) of information that we have are as follows:

• Motivation: Projectile motion is a common problem in physics.
• Background: (not currently in the example, but we could add it) Common examples of projectile motion include ballistics problems (missiles and bullets) and the flight of the balls in various sports (baseball, golf, football, etc.).
• Name of the Software: The program documented here is called Projectile.
• Purpose: Given the appropriate inputs, Projectile determines if the projectile hits a given target.
• Roadmap of Introduction section: This section explains the purpose of the document, the scope, ...
• Scope: The scope of the requirements includes the analysis of a two-dimensional (2D) projectile problem with constant acceleration.

If we had each of those pieces of information separately codified, we could reuse the ones that are relevant in the README file, or elsewhere. The purpose in particular would make sense in the code files.

[JacquesCarette]

@smiths provides a superb, in-depth analysis of the situation. This is a great model to follow.

[peter-michalski]

Purpose

The purpose is currently given in the last sentence of the scope section: "Given the appropriate inputs, Projectile determines if the projectile hits the target."

I'm not seeing this verbatim in the SRS. I see something else entirely in the Scope of Requirements section.

The 'purpose' you are suggesting is a fusion of the information under the Goal Statements section of the SSD. Specifically the lone goal in this example as well as phrases passed directly into the SRSDecl of Body.hs.

Drasil/code/drasil-example/projectile/lib/Drasil/Projectile/Goals.hs

Lines 9 to 15 in 84272ac

	goals :: [ConceptInstance]
	goals = [targetHit]
	targetHit :: ConceptInstance
	targetHit = cic "targetHit"
	(S "Determine if the" +:+ phrase projectile +:+ S "hits the" +:+. phrase target)
	"targetHit" goalStmtDom

In this case, we should look at the relationship between purpose and goals, each as "groups of fragments of information", to see if we can encode them in a way that eliminates duplicate fragments.

The purpose is a brief abstract statement that characterizes what the software does.

This overlaps with our goals. We can see this relationship by looking at other examples:

SWHS:

• Predict the temperature of the water over time.
• Predict the temperature of the phase change material over time.
• Predict the change in heat energy in the water over time.
• Predict the change in heat energy in the PCM over time.

GlassBR:

• Analyze and predict whether the glass slab under consideration will be able to withstand the explosion of a certain degree which is calculated based on user input.

Looking at the syntax, a simple change to the capitalization of the goals would allow us to combine them into a purpose. They can then be re-capitalized when printing the information as goals.

Background (What) and Motivation (Why)

It looks like we will want to generate both the motivation (Why) and background (What) information in the READMEs.

For projectile, as @smiths suggested, the start of the introduction section can be used for the motivation.

A background blurb will also need to be added. It will need to sit in Body.hs for now. I don't think it's appropriate to add it to any of the other files.

For the other examples, it looks like we can pick out part of the introduction for our motivation, specifying the need for the software. Background will also need to be added to each example, with the semantics suggested by @smiths in #3206. The background will list common examples of the problem being addressed by the software.

Other SI fields

I will go ahead and add the the following fields into SI

• Motivation
• Scope
• Software review

Roadmap of Introduction section

This would probably be artifact specific, and not in the SI.

I will also update README generation to add the following blurb to the project name: "The program documented here is called"

Example Projects

This is higher-level than the SRS. I think this is what SystemInformation was heading towards

It is probably a good idea to start thinking about splitting apart the current content of Body.hs, separating artifact specific details from the meta-information that will be used in multiple artifacts.