Follow-up to #4409: Requesting approval of standard introduction template

[JoeZZG]

This issue continues the discussion in #4409 about the defining a standard introduction template for all example SRSs. Please take a look at the template.

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.

In a specific example of HGHC: Context → first sentences in the paragraph (“Heat transfer through…” / “Engineers therefore…”). FullName + ShortName→ “This document describes…”. Provenance + ProvPlace → “based on the original…” sentence (unused). PurposeSent → the purpose sentence (“The primary purpose of this document…”). Examples → optional “Examples include …” sentence (unused). SrsSubject → 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.

[smiths]

@JoeZZG I put comments on the introduction for HGHC in #4409. Please address those comments to revise the introduction.

I don't think you need the provenance placement option. If it is there, I believe it can be expressed in one sentence.

Does your template work for all of the case study examples? Is there information in the existing examples that will have to be removed if we use this template?

[JoeZZG]

Control Paramater context = 1-3 sentences background (required) fullName = phrase progName (required) shortName = short progName (optional) provenance = namedRef to external link (optional) srsSubject = phrase progName (required)

Template <context> This document describes the requirements of a program called <fullName> (<shortName?>) [if provenance], which 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.

New Introduction for HGHC Heat transfer through the cladding of a nuclear fuel element influences performance and safety. Engineers therefore rely on dependable calculations of the heat transfer coefficients used for simulating the temperature. This document describes the requirements of a program called HGHC.

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.

Control Parameters for HGHC context = "Heat transfer through the cladding of a nuclear fuel element influences performance and safety. Engineers therefore rely on dependable calculations of the heat transfer coefficients used for simulating the temperature." fullName = HGHC shortName = None provenance = None srsSubject = HGHC

I have updated the template to make it easier to control, in which context can be multi sentences so that the existing context can just be pasted in. I also revised the introduction for HGHC. This template should fit all the examples. There is no need to remove any information from the existing examples when using this template.

[smiths]

The new introduction for HGHC sounds good. However, isn't the fullname already available? Hasn't this information already been captured?