Should we generate @smiths' official SRS template?

[balacij]

@smiths has an SRS template he uses for CAS 741 and capstone projects (and, of course, a series of related papers). In CAS 741, we built our own scientific computing projects with the document-driven approach we advocate for. However, I worked on Drasil before fully going through the SRS template. After reading through the SRS template, I gained insight into more of the workings of the SRS. After building an example using the SRS template, I reinforced and expanded on my learning.

So now some questions come up:

1. Should we try to generate @smiths annotated, descriptive version of the SRS template?
2. Should we try to similarly build a Drasil-oriented example that users can use to learn about the SRS template while building a simple program that calculates something common (say the hypotenuse of a right-angled triangle and the area of that triangle)?

(1) might not be very useful, but it might prove to be a nice exercise in Drasil to (a) show that Drasil is capable of doing anything that LaTeX users should be using when building SRS documents strictly, and (b) figure out how the existing SRS document abstraction lacks the features of the LaTeX copy and close the gap.

(2) might be a bit more useful for onboarding new users of Drasil and adopters of the document-driven approach.

[balacij]

To be clear, I'm "pro" both (1) and (2).

[smiths]

@balacij, I'm also in favour of both of these ideas. If we take (1) seriously (that is, if we improve on what I wrote as guidance notes to the 741 students), we could have something useful. When people are building their knowledge inside Drasil, it would help to see the "big picture" of how the knowledge is intended to be related. It would also help us clarify the relationship between the different sections of the document, like the relationship between scope and assumptions. We probably would also gain some insights into how we can automate building more of the sections. The notes I added to the template are rationale and explanation information. We've been talking about adding "extra" information to pieces of knowledge in Drasil, so this would force us to think about how to capture this knowledge.

However, I think we probably should wait to codify the template until we've explored the notion of a template that explicitly incorporates theory refinement. It is too implicit in our current template.

With respect to (2), I like the idea of a simple example to help users learn Drasil. An example of mathematical knowledge, like application of the Pythagorean theorem or the area of a triangle would be interesting to look at. Those are both examples of mathematical knowledge. I'd be curious to see if it would simplify the template too much, since there aren't really any assumptions. We might want to instead look for a simple physics problem, just so we can show the role of assumptions?

[samm82]

I think even expanding the Template example to generate the CAS 741 template will provide a better overview of what the document is and how to think about filling it in, as well as providing a more useful template in the context of Drasil

[JacquesCarette]

I agree that the "use theory refinement" project should happen first, then this.