Drasil Define Standard Introduction Template for All Example SRSs

This issue is under PR #4406 and Issue #3529. In that PR, I added new introduction templates and applied one in an example.

In the last group meeting, Prof. Carette said the templates should be more functional/structural and maybe not general enough. I am not fully sure what that means. I would like to ask for suggestions on how to make the templates better and more general.

Please share thoughts on:

What “more functional” could mean in this context.

How to make the template and reusable.

Whether my current code and structure in PR #4406 are on the right track.

Any feedback or examples are very welcome. Once agree on the changes, I can update the code and apply the new template to other examples. Sorry I did not follow the standard procedure of a PR.

Oct 20 '25 15:10 JoeZZG

What I mean:

read all of the introduction paragraphs for all examples [analysis]
extract out the repeated patterns (with potentially singling out a couple of examples as outliers) [synthesis]
implement a template based on abstracting out the repeated patterns into commonalities as structure, and variabilities as parameters [implemention]

Oct 20 '25 21:10 JacquesCarette

I tried to follow the instructions, by reading through the introductions and analyzing the patterns, and created some pseudo templates of the introduction.

Analysis

Shared elements: Shared naming: Most have a sentence “The document describes the program called <Full Name> (<SHORT>).” Provenance: “...based on the original, manually created version of ” with a link. Purpose: one sentence pulled from variable purp or purpDoc. SRS template: the same “This section explains purpose/scope/reader/organization” line.

Outliers: HGHC: it has no intro paragraph. Some have no IntroSection file. Provenance is sometimes embedded, sometimes at the end.

Optional elements: Abbreviation: some have short names, some do not. Provenance clauses can appear inside of a sentence or as a tail.

Synthesis of blocks

Required: Context: One or two sentences that frame the domain motivation. Parameter: context :: [Sentence]

System name: “The document describes the program called <FullName> (<ShortName>).” Parameters: fullName, shortName.

Provenance: “..., which is based on the original, manually created version of <Name>” + externalLinkRef.

Purpose: Using purpDoc / purp for “what the software does”.

SRS template: “The following section provides an overview of the Software Requirements Specification (SRS) for <FullName>. This section explains the purpose of this document, the scope of the requirements, the characteristics of the intended reader, and the organization of the document.”
Parameter: phrase progName

Abbreviation: On the first mention in the intro: “Full Name (SHORT)”. Use from abbreviationsList, short progName.

Implementation

Template A (when have a short name and provenance inline)

<background>
This document describes the requirements of a program called <phrase progName> (<short progName>), 
which is based on the original, manually created version of <namedRef externalLinkRef (S "...")>.
<purp | purpDoc progName Verbose>
The following section provides an overview of the Software Requirements Specification (SRS) 
for <phrase progName>. This section explains the purpose of this document, the scope of the 
requirements, the characteristics of the intended reader, and the organization of the document.

Template B (when does not have short name but has provenance inline)

<background>
This document describes the requirements of a program called <phrase progName>, 
which is based on the original, manually created version of <namedRef externalLinkRef (S "...")>.
<purp | purpDoc progName Verbose>
The following section provides an overview of the Software Requirements Specification (SRS) 
for <phrase progName>. This section explains the purpose of this document, the scope of the 
requirements, the characteristics of the intended reader, and the organization of the document.

Template C (no provenance, e.g., HGHC)

<background>
This document describes the requirements of a program called <phrase progName> (<short progName>) (<optional>).
<purp | purpDoc progName Verbose>
The following section provides an overview of the Software Requirements Specification (SRS) 
for <phrase progName>. This section explains the purpose of this document, the scope of the 
requirements, the characteristics of the intended reader, and the organization of the document.

Template D (provenance as tail, e.g., SWHS PCM)

<background>
This document describes the requirements of a program called <phrase progName> (<short progName>).
<purp | purpDoc progName Verbose>
(<domainNotesSentences>)
<phrase progName> (<short progName>) is based on the original, manually created version of 
<namedRef externalLinkRef (S "...")>.
The following section provides an overview of the Software Requirements Specification (SRS) 
for <phrase progName>. This section explains the purpose of this document, the scope of the 
requirements, the characteristics of the intended reader, and the organization of the document.

Please make some comments. Once they are approved, I will implement in Body.hs and other files of each example

Oct 21 '25 13:10 JoeZZG

Nice analysis @JoeZZG. It sounds like from the above that Provenance is a required piece of information. I think we could make this optional. Many of our examples are derived from pre-existing software, but not all of them.

I'd also like to add optional information on Examples. For some of our problems, examples can help clarify the purpose. For instance, I added examples in a version of Projectile that was hand written to explore theory refinement. The examples are helpful to explain things to the readers, and they can be used to help define/explain the scope.

Oct 21 '25 15:10 smiths

Comments:

I would fix HGHC to have an intro paragraph
I would add an IntroSection to all examples
I agree that abbreviation and provenance should be optional
There should not be 4 templates, there should be a single template with control parameters

Oct 24 '25 14:10 JacquesCarette

I have summarized a template. Please take a look:

Control Parameters:

context = <background> (1–2 sentences)
fullName = <phrase progName>
shortName? = <short progName> (optional)
provenance? = <namedRef externalLinkRef (S "...")> (optional)
provPlacement = Inline | Tail
purpose = <purp | purpDoc progName Verbose>
examples? = <examplesSentences> (optional)
srsSubject = <phrase progName>

Template:

<context>
This document describes the requirements of a program called <fullName>(<shortName?>)[if provPlacement=Inline & provenance] , which is based on the original, manually created version of <provenance>.
<purpose>
[if examples] Examples include: <examplesSentences>.
[if provPlacement=Tail & provenance] <fullName>(<shortName?>) is based on the original, manually created version of <provenance>.
The following section provides an overview of the Software Requirements Specification (SRS) for <srsSubject>. This section explains the purpose of this document, the scope of the requirements, the characteristics of the intended reader, and the organization of the document.

If it looks good, I will implement and add new IntroSection, so as one for HGHC

Oct 26 '25 10:10 JoeZZG

Looks good. Though I would definitely want @smiths to review the provPlacement variability to see if it is actually wanted.

Oct 27 '25 20:10 JacquesCarette

in HGHC:

introContext → first sentences in the paragraph (“Heat transfer through…” / “Engineers therefore…”). introFullName + introShortName→ the program name clause in “This document describes…”. introProvenance + introProvPlace → inline or trailing “based on the original…” sentence (HGHC currently leaves this absent). introPurposeSent → the purpose sentence (“The primary purpose of this document…”). introExamples → optional “Examples include …” sentence (unused for HGHC). introSrsSubject → it holds phrase progName.

the new introduction looks like: Heat transfer through the cladding of a nuclear fuel element influences performance and safety. Engineers therefore rely on dependable calculations of the associated coefficients. This document describes the requirements of a program called HGHC. The primary purpose of this document is to record the requirements of HGHC. Goals, assumptions, theoretical models, definitions, and other model derivation information are specified, allowing the reader to fully understand and verify the purpose and scientific basis of HGHC. With the exception of system constraints, this SRS will remain abstract, describing what problem is being solved, but not how to solve it.

The following section provides an overview of the Software Requirements Specification (SRS) for HGHC. This section explains the purpose of this document, the scope of the requirements, the characteristics of the intended reader, and the organization of the document.

Nov 04 '25 18:11 JoeZZG

In the HGHC example "Engineers therefore rely on dependable calculations of the associated coefficients." should be changed to "Engineers therefore rely on dependable calculations of the heat transfer coefficients used for simulating the temperature."

There should be a newline (to start a new paragraph) after the name of the software (HGHC).

Your roadmap of the SRS ("Goals, assumptions, theoretical models, definitions ...") is incorrect. You are mentioning parts of the report that are not in the HGHC SRS. There are no Goals given in this example. Similarly your mention of system constraints is wrong. There are no constraints given for HGHC.

Your last paragraph of the HGHC introduction should be removed.

@JoeZZG please create an issue for approval of your revised HGHC introduction so that we can discuss it there.

Nov 08 '25 00:11 smiths