Adding Scope and Motivation Fields and Defining the Role of the What Section in README Files

[Xinlu-Y]

This issue relates to both issue #3159 and #3248. Based on the comments above, generating a comprehensive software review isn't feasible for us at the moment. The main goal is to ensure that the scope and motivation are available in both the SystemInformation and in the README files.

• We can update the following sections in the generated README files for each example's src directory:
  • Example name
  • Authors
  • Motivation
  • Purpose
  • Scope
  • Making Examples
  • ...
• For instance, taking the Projectile example, the README could look like this, where Purpose, Motivation, and Scope are optional subsections under introInfo:
  • Projectile
  • Authors: Samuel J. Crawford, Brooks MacLachlan, W. Spencer Smith
  • Motivation: Projectile motion is a common problem in physics.
  • Purpose: Predict whether a launched projectile hits its target.
  • Scope: The scope of the requirements includes the analysis of a two-dimensional (2D) projectile problem with constant acceleration.
  • Making Examples
    How to Run the Program: In your terminal command line, enter the same directory as this README file.
  • ...
• Additionally, a What section has already been created in the current code, but currently, it holds no information in the generated README file.

  Drasil/code/drasil-printers/lib/Language/Drasil/Markdown/CreateMd.hs

  Lines 33 to 35 in e72dd92

  	-- | 'What' section in generated README file, does not display if empty
  	whatInfo :: Maybe String -> Doc
  	whatInfo = maybe empty (regularSec (text "What") . text)

• I'm considering whether we could use this section to include relevant background information. If so, the What section might look like this:
  • ...
  • Scope: The scope of the requirements includes the analysis of a two-dimensional (2D) projectile problem with constant acceleration.
  • 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.).
  • Making Examples
  • ...

We need to decide whether it's necessary to keep the What section and, if so, what information should be included in it. One possibility is to move some of the content from introInfo to whatInfo. For example, we could have introInfo focus on answering the "why" questions (motivation, purpose), while whatInfo could address the "what" questions (background, scope).

[JacquesCarette]

This is an excellent proposal! Yes, please start designing exactly this.