TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• "Symbols, Abbreviations, and Acronyms" shouldn't be capitalized in the paragraph before the table.
• I think saying "SRS document" is redundant; I would just say "SRS".

Personal Preference

• I think the description of "CAS" should just be "Computing and Software", since that is what it stands for. This is a little tricky, since there isn't a Terminology and Definitions section like in the SRS where more detailed information could be captured, so this is up to you.
• I would be more explicit about which symbols, etc. are used in the VnV (something like "In addition to the ones from the SRS, the following symbols, etc. are used in this document.").

Note that the base SI unit is kilograms, so you do not need to define it in terms of grams. You would, however, need to define grams in terms of kilograms if used in the document (something I didn't do 😅).

Since there aren't any specification parameters in the Input Variables table you should remove the table for them, along with all references to it (assuming you don't add any parameters as part of #19).

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• I'm also not sure if the adjective "provided" in the System Context paragraph is needed. If you decide to keep it, you should explain what it means: who is providing it? This would likely mean adding something to the System Constraints section.
• "BeamBending" shouldn't be in quotation marks, since it is an established term in the document.
• There shouldn't be a comma after inputs in the last sentence, since there are only two items in the list ("use a provided..." and "output the ...curve."
• The inputs and outputs to the BVP could be specified more: what data gets sent to the solver?
• Since you are using an external Boundary Value Problem solver, it should have its own associated responsibilities.

In your section 5.2,

Again, it looks like lack of testing plan. I guess you can give more and accurate details about non-functional tests by concentrating "How you can get confident that you achieved it?"

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• This section doesn't need to be on its own page.
• Including '"whole"' before "Verification and Validation plan" isn't necessary; the plan should be complete, but even if it isn't, this should be "faked" as per the documentation process.
• "Responsibilities" should be capitalized in the Table of VnV Roles.
• For consistency, configuration requirement 1c should be "with “full” modularity."
• Since other new terms/technologies aren't bolded on their first introduction, neither should "pytest."
• The phrase "the author" in the Software Validation Plan section is ambiguous since you introduce the hypothetical writer of a textbook in the previous sentence. Maybe say "the author of this document" instead?

Personal Preference

• According to Wiktionary, "subplan" and "subteam" don't have hyphens, but I don't think it is incorrect to keep them.
• Likewise, "nontrivial" also shouldn't have a hyphen.
• I would say "the unit tests will be performed on the generated software artifacts" instead of "the unit tests will be ported over to the generated software artifacts."

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• There shouldn't be a comma after "categories".
• The description of the Testing Inputs Are Outputted Accurately section is quite confusing.
  • If kept the way it is, it should have a comma after "testing".
• Do you mean to exclude $0$ and $L_B$ as values of $x$ when testing the BVP solver?
• It should be "The expected outputs will be confirmed...."
• What ranges of values of $E_B$ and $I_B$ will be chosen?
  • I would rephrase to avoid saying " $E_B$ s".

• Ratios should only be represented as percentages when they are used as the ratio of a part to the ratio of the whole (source); since $SLENDER$ is the ratio between two different dimensions, it should just be a decimal number.
• As they are just relationships between two numbers, the units of ratios cancel out (i.e., SLENDER shouldn't have a unit of meters).

Comment for your section 4.5,

It looks like you have focused highly on "How implementation will done?" I think you can highlight it. But mainly, you should focus on plan for implementation testing. For example, you can give more details about how you can perform code walkthrough and who will take participation in it? Or How you will conduct peer review?

The following is a list of grammar, formatting, etc. issues that weren't in sections with another issue in them or that were in sections with only one other issue in them.

TODO

Any point that requires more discussion should be pulled out to a different issue.

• I think your subtitle should start with a capital letter, and I'm not sure it should have a period.
• Throughout the document, it should either be "2D" or "two-dimensional", not "2-dimensional".
• In Subsection 2.1, I think "so (that)" would be a better word choice than "such that" in "The document provides sufficient information such that...."
• In Subsection 2.1, "increased" doesn't need quotation marks, as you immediately justify why the "degree of confidence in reliability and correctness" is increased.
• Not a critique, but I could almost audibly hear you say "adequately codified". 😂
• In Subsection 2.2, "subsection 4.1" should be capitalized.
• In Subsection 2.2, since you define what the problem is, or at least where to find it, you should also define what the solution will be (i.e., "the program specified by this document", etc.); I am unsure if the quotation marks around "problem" and "solution" are necessary.
• In Subsection 3.1, verb tenses for responsibilities should be consistent (e.g., "Providing" vs. "Interpret").
• In Subsection 3.2, consider using "...applied in educational contexts..." or "...applied for educational purposes...."
• In Subsection 3.2, there shouldn't be a hyphen in "simply-supported".
• In Subsection 4.1, "...deflection experience by the beam..." might be more clear.
• I think "Detailed derivation of simplified rate of change of temperature" in Subsection 4.2.3 is a mistake.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• Is it intentional to include "domain expert" in the Supervisor role when it is its own separate role?
  • If so, remove the "and" before "distinguished reviewer" in the Supervisor description and add the Oxford comma to be consistent with the rest of the document.
• The description of the Author role is not really informative.
• The Verifier and Validator roles seem restricted in scope. They should also involve the verification and validation of the code itself when created.
• Are you also a domain expert?
• Maryam's project is really the Drasil implementation, not Drasil itself.
• The class members aren't supervisors, so they shouldn't have all roles.
• The description of the "*" should be more fleshed-out.

Watts are used in DD1 and should therefore be in this table.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• Your test cases for the NFRs should be rephrased to describe the process of verifying them instead of describing why they are verified.
• Your test for accuracy does not satisfy your NFR for accuracy.
• "Three" should be spelled out (also in the SRS).
• Your usability test should direct to the Usability Survey Questions section of the appendix.
  • Related: if you are not testing for accessibility, than you should omit accessibility from the Usability Survey Questions section.
• "Regeneration" does not have a hyphen.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• The sentence "The choice of symbols was made to be consistent with the heat transfer literature and with existing documentation for solar water heating systems." is borrowed from the template and does not reflect your project.
• You say "The symbols are listed in alphabetical order," but they are not.
• Subscripts with words should not be italicized (i.e., R_{\text{Pinned}}).
• Consider an alternate way to display/name "Pinned" and "Roller"; perhaps change their names or use \text{} for them as well, since they are words and not variables (P*i*n*...).
• From what I can tell, "n+1-dimensional" should be formatted as "(n+1)-dimensional" to be more clear.
• The following symbols are missing: $\rho$, $x$ and $y$ (in the context of TM1), $M(x)$, and $EI$.

IM1 is missing Source and Ref By information - if there is none, they should be filled with "--" or "N/A" to indicate that this was intentional.

I'm not sure if this is captured by the second FIXME comment below, but you should use the symbolic representation of $w_B$ (which should be straightforward since the definition is a Sentence

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• There seems to be two assumptions in A1 (2D + observed at moment of load placement).
• The definition of "slender" should be moved to the Terms and Defs section.
• A2-A4 should be better formatted. Consider describing the beam as prismatic in the System Context section, then just listing A3 and A4 as their own assumptions (not as sub-assumptions of A2).
• From what I can tell, "linear-elastic" shouldn't have a hyphen.
• The wordings of A9 and A10 are confusing.
• Either traceability between assumptions and what reference them is not included, or your assumptions are not used by the rest of the document.

Hi @Maryamvalian and @samm82, I just wanted to let you both know that @smiths extended the deadline for the Drasil code (until the 29th 😄). Of course, I'll try to have the code ready earlier than the deadline. Thank you for your patience 🙏

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• "At-rest" doesn't need quotations.
• The list of elements in the figure is duplicated in the list of components in the physical system; consider removing the first list.
• You use the subjective word "slender"; either use a more precise word or define it in the Terminology and Definitions section.
• You also use the word "determinant" and italicize it; since it is so significant, you should define it as well.

Just creating this ticket to track my work on addressing @smiths' feedback :)

The Drasil SRS code is ready for review. I focused on building on code generation, but failed by the end of the March 29th deadline. Hopefully I'll be able to make some progress on it before the end of the course, but definitely before the summer. I've created several tickets on the main Drasil repository JacquesCarette/Drasil.git, and I'll be creating more as I go along.

All code relevant to my attempts were mentioned in my presentation on Thursday March 30th and are public (on the beamBending and bmBndngNoFunctions branches, deviating at the type of y_B [the deflection function] being a function, or a vector -- which is what Drasil prefers for the code generation). On both branches, the artifacts can be found in the stable folder, and the source code can be found in the drasil-examples folder.

The original SRS is also available and will likely need to be used for reference.

• @smiths
• @samm82
• @Maryamvalian

• In your general Information section (3) you wrote "Plan of action" - I guess this is a wordy statement.
• In section 4.7 (Software validation plan) Last statement "Input, output, ..." is ambiguous.
• In table 3: you wrote "Simple, Automatic, Tests" for table caption. Is it intentional? I guess "," (Comma) is not required.
• I found one infinity sign outside of the table 3. You can place it somewhere.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• "Beam Bending" shouldn't be capitalized in the General Information section.
• I would be a bit more specific about the purpose of verification (something like "...and verifying that a software built following the SRS actually satisfies the listed requirements."); the sentence as-is is quite confusing and unclear.
• There shouldn't be a comma after "imposed" in the Summary section.
• There shouldn't be a hyphen in "simply supported".
• There seems to be duplication between the General Information section and the Objectives section; maybe remove the descriptions of validation and verification from the General Information section?
• There shouldn't be a comma after "requirements" in the last sentence of the Objectives section.
  • This sentence is also quite confusing; consider rewriting it for clarity.
• The documentation generated by Drasil (e.g., the generated SRS and, if you decide to count them, code comments) is also relevant; this documentation should be added to the list, even if it does not exist yet.
• The last sentence of the Relevant Documentation section should say "...that we can add to the above list" (or something similar).

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• "End-user" (and related words) only have a hyphen when they are an adjective, not a noun.
• What does "meaningful" mean in R2?
• There isn't any requirement for the BVP solver; does input need to be formatted to use it?
• What does "well-defined" mean in R4?

Your section 5.1.1 to 5.1.3 are too confusing.

Reasons:

• - I guess you wrote two subcategories of 5.1.1 are 5.1.2 and 5.1.3. - So, it should be either sub sub categories.
• - Also, same table for both subcategories make it even more confusing. - I think you should separate it for different subcategories.
• - How testing for "testing output with non-trivial inputs" is performed? - It's not clear.

You can work on it to make it better.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• Should the citation of TM1 be moved to after the description of the variables?
• Description missing for TM3.
• You say "Derivation for TM3" is "Not Applicable", then supply it below.
• In the derivation (?) of TM4, either use parenthetical commas or parentheses when naming $w(x)$, not both.
• #67

• As Prof. Smith told when you were presenting, It's better to use appropriate arrow to show rotations on figure 2.
• The word "slender" used in section 4.1.2 without prior definition, however the definition is in assumption A2, It should be added to Terminology section. #13
• I didn't get the way A9 and A10 in assumptions are written.
• TM3 needs description to be added. #17
• In TM3, You show how TM# is derived from TM1 and A8, so the "Derivation for TM3" is applicable.
• The sources and Ref.By parts in IM1 are missed.#18
• I saw the issue#20, however I think it's better to consider what Prof. Smith told to me, "For a section of a template, if you don't use it, keep the title and enter "Not applicable". If it isn't obvious, explain why the section is not applicable. I don't think I explicitly mentioned this in class, but with a standard template you don't want to delete sections. If someone reads the document and a section is missing, they don't know if the author forgot the section, or intentionally removed it." In fact, the quotation was about the whole section but I think we can apply the same way for the subsections too.
• In NFR1 and 2, you refer to Section X of V&V plan which is not written yet. They are relatively ambiguous.
• Table 4 in section 8, should be revised, as it is like a symmetric matrix, but your table is not and should be completed.
  Thanks.

I didn't go into detail here since Drasil will do this automatically, but each "X" in a matrix represents an explicit reference. Many of these are missing (For example, none of the LCs reference an assumption.)

Minor issue, but Table 6 probably doesn't need to be on its own page.

Related to #6; I'm not sure if "the user of this software should be a civil engineer or equivalent," since the user of the software could be more general than that. An engineering firm might have a co-op student that they get to do some simulations and make a presentation on to get some alternatives for licensed engineering to independently evaluate (assuming that this is something that could happen in practice).

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• The list of terms should be sorted alphabetically for ease of navigation.
• Make sure the plurality of each term matches its definition. For example, since "beam" is singular, its definition should be too: "structural components intended...."
  • Related: either all terms should be singular or all terms should be plural for consistency.
• There shouldn't be a comma in the definition of simply supported beam.
• Your examples for shear forces are really examples of things that exert shear forces, not the forces themselves; this could be made more clear or different examples could be used.
• "Modulus of elasticity" should be listed as a separate definition in case the reader is looking for it alphabetically, doesn't find it, and gives up. The definition of "Young's modulus" should then point to the definition of "modulus of elasticity."
• Most terms start with "the", but some done (e.g., "moment of inertia").

• Only introduce acronyms on their first usage (e.g., the phrase "Software Requirements Specification (SRS)" should only appear once the first time it is used).
• When talking about the Verification and Validation Plan (or VnV Plan), make sure to capitalize "Plan", since it is part of the document title.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• Who will be the one "checking that BeamBending’s Software Requirements Specification (SRS) conforms to Dr. Smith’s provided SRS checklist"?
• I don't think that the phrase "The software design does not need verification..." is correct. The software design should be verified, but it's OK if that is left to the Drasil team (as the validation is).
• Who are the "many eyes" or the "team member[s]" who will be looking over the VnV? Everyone in your Table of VnV Teammates? Only some of them will be looking at the VnV.
• It seems weird to me that the "many eyes" hypothesis is only introduced for the VnV Plan and not other artifacts.
• In the Implementation Verification Plan section, should it say "The generated software artifacts should be tested against the manually created artifacts to see if if non-trivial or significant differences exist;" presumably you will be testing the generated version against the manual one even if there aren't major differences.
• You should explain why "we have faith in the Drasil work."
• What does "aggressively formatt[ing]" the Python code entail?

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• Many sentences make claims that should be backed up (e.g., "For any structure carrying load, beams are used to...", "Unlike flooring in residential homes, we expect..."). These might be common knowledge to a domain expert, such as the intended reader of the document, so Dr. Smith might need to weigh in on this one.
• There is likely other software that can be used to "analyze the beams reaction under various loading scenarios", so it sounds a little presumptuous to say "We call the software that performs this, 'BeamBending,'" as if it is and will be the only piece of software to do this.
• It should be "We call the software that performs this 'BeamBending,'" without the colon.
• You define what a "simply supported beam" is but never reference it again; will BeamBending focus on simply supported beams?

Throughout the table of symbols, a symbol with the subscript "B" seems to indicate that it is the concrete version of the quantity:

However, $w$ and $w_B$ seem to break this pattern.

While this isn't necessarily an issue, I just wanted to make sure this was intentional

I am not sure but how your functional requirement (R1) is used in you given test cases? Also, your functional requirement (R1) is trace with the Non-functional requirement in table 4?

Not only is "BeamBending" neither an abbreviation nor an acronym, but, if included here, its description is not particularly informative.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• Drasil currently uses "undergraduate level 2", etc. to refer to levels of post-secondary education; you might consider doing this for consistency.
• I'm not sure that the necessary concepts from physics need to be explicitly described, since a lot of them seem trivial.
  • I'm conflicted about this, since I'm not sure if I learned about elasticity in first-year physics.
• If included, the necessary concepts from physics do not need quotation marks.
• Drasil also uses "It would be an asset to understand _" to introduce unrequired but beneficial knowledge; you might consider doing this for consistency.
• The final sentence should be more explicit. What does "non-trivial" mean? If an engineering student tries to build a structure, is that OK since it is experiential learning (and thus not "non-educational")? I'm not sure if the reading of this document can/should be restricted.

I've done my review too. The comments are in the attached pdf file.
plan-Fdbck.pdf

Originally posted by @smiths in #28 (comment)

I just have to add Deesha to the repo too, but I'll assign her too.

One caveat is that I didn't mention any units in this document. I need to make a choice and fix my SRS first, and then I will update this document.

Another caveat is the abstract vs concrete symbols. I haven't changed them (yet) -- I will send @smiths a message about it soon!

Dear @balacij,
Thank you for your efforts, I enjoy reading your SRS.
These are some comments that I hope make it better. I know that some of them are repeated as Sam mentioned them before and I am sorry, however I try to find the related issues and refer to them.

• The title should start with capital letter and end without period.
• The first two tasks made by Sam on #3.
• I found some " " in different parts of the document which should be revised, such as Beam Bending and increased in the section 2.1.
• As you mentioned in GS2, your tool have two outputs, so it should be added at Figure1 and on the arrow of Output.
• As a part of system context in figure1 and used in IM1, BVP Solvers' responsibilities should be added.
• The arrow between BeamBending and BVP is bidirectional, what data is exchanged between them?
• The first responsibility of the user tells that user should provide assumption. The assumptions of your system are not fixed? user can change them? I think it should be deleted.
• I agree with Sam on issue#9, a general description is preferred.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• This section doesn't need to be on a new page.
• What do you mean by "we will bootstrap the Drasil-generated software artifacts for testing"?

• I think the data flow to/from the BVP Solver should be shown as separate arrows with briefer descriptions to match the format of the data flow to/from the user (e.g., "BVP specifications" is shown by the arrow going to the solver and "BVP solution or error" is by the one from the solver).
• The description about the notation used in other examples (and your manual SRS) should be added. You likely already know about this, but just making sure.
• Why is the caption lowercase? Is this something else you assumed would be done automatically or was it just an oversight? (The Physical System Description section has this same issue.)
• Minor thing, but I don't think the periods are needed/useful lol

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• What is the "level [of accuracy] needed for civil engineering? A source might be helpful here.
• It should be "visualization" and "reiterating".
• What does it mean to reiterate information? Are these additional outputs?
  • What does "important" information entail?
• What do the phrases "relatively straightforward and already well-understood" and "clear impact" mean in NFR3?

• I would change the definition of "slender" to "having a length-to-height ratio of at least 10:1".
• Inconsistent article usage ("beam" and "deflection" don't have articles while "bending moment" and "load" do).
• The quotation marks in "beam" should be built with Quote, which is a Sentence constructor, so the whole term will have to be built with nounPhraseSent instead of nounPhraseSP
• Should the definition of "shear force" say "...to an object"?
• This list should be sorted alphabetically (which can easily be done manually, but is still a Drasil-specific issue: JacquesCarette#1432)

SRS PDF

Two important caveats:

1. I haven't been able to figure out a general "calculate the reactions at the supports" algorithm yet.
2. I need to plaster citations everywhere (it's mostly the textbook that I borrowed from @smiths and various online resources).

(also note that I can't assign Mina until she's accepted the invitation to collaborate on this repo, which I've just sent!)

Software constraints should describe what kinds of input you accept; traditionally these bound a value between a min and max. The constraint that the values be positive are already captured as physical constraints, so you don't need to repeat them.

The following acronyms appear in the table of acronyms, but not in the actual document: DC, DS, MG, MIS, and NB. PS also doesn't appear, but I'm guessing this will be added later.

My guess is that you populated the acronyms field with all terms that have acronyms, but Drasil doesn't currently work like this. Correcting this so that the table is populated with only the used acronyms is likely going to be part of Drasil generating content based on the existence of other content in the document.

TODO

Any point that requires more discussion should be pulled out to a different issue; I grouped these all here since they are related and small.

• The list of inputs seems ambiguous. There should be a "the" in front of each input; without it, it implies that the constant length and modulus of elasticity are also across cross-sections of the beam as well (which might be the case; if so, there should only be a "the" in front of "constant length").
• There shouldn't be a comma after "beam".
• What is the point of calculating the reaction of the supports under load? If it is outputted to the user, it should be in the System Context section.

As noted by the template itself, "The template description comments should be disabled before submitting this document for grading."

I noticed your comments in TheoryModels.hs:

Note that you don't need a source if you use the tmNoRefs constructor. This implementation forces the user to explicitly decide if they want to include a source instead of naively passing in an empty list to just try to get a minimal viable product and potentially leave a TM unsourced.

(Feel free to either use tmNoRefs or keep your current "placeholder" sources; this just seemed like the best way to let you know lol)