"Characteristics of Intended Reader" and background knowledge

[balacij]

(Getting this down before I forget, but we briefly discussed this in our last in-person meeting. I can't spend too much time writing this, so it will be a bit rough. Sorry in advance!)

Taking NoPCM's “Characteristics of Intended Reader” (CIR) section as an example, when we list the bundles of requirements, we're recognizing that the SRS artifact relies on some assumed (“basic”) set of knowledge. The mention of "calculus 1 and 2" means that there is some body of knowledge it pulls on which can be found in common "calc 1 and 2" classes, and that body of knowledge might come with a presupposed set of assumptions, theories, and the likes (this might be more relevant when we say "undergraduate-level physics" however).

Aside: The import might optionally come with a specific notation (which would be shown in a nearby section).

However, that set of knowledge is what the remainder of the SRS relies on. Interestingly, in the “backend” (the source code), we're also “importing” a similar set of knowledge and limiting ourselves to working with just that set of imports.

In the context of #3003, if we had the source code of the examples externalized, then the CIR section might be generate-able (?) by analyzing the theories and the “imports.” If we capture the metadata about where those theories and imported knowledge might be found, then we could suggest recommendations for where they might be found too, such as in “common North American undergraduate university level 1 courses in

It's a bit wishful, but it's a thought. At the very least, this post is about recognizing that the CIR section is related to the background knowledge and the "import set" (which might include relevant syntax, theories, etc.).

[smiths]

@balacij I think you got down the discussion points quite well. Good to have this recorded somewhere. We are a long way from automatically generating the CIR section, but it is good to have an ambitious vision. 😄

[balacij]

Thanks! I hope this trend of looking at the English bits again (e.g., #3259 – thinking about how we can capture the ideas and generate the English) continues. 741 definitely helps with it 😄

[JacquesCarette]

"Looking at the English bits" is, to me, a proxy for more deeply understanding the link between our informal (aka natural language) descriptions and the formal version of the same. Our natural language bits encode quite a lot of information that we need to 'tease out'. We do a similar task when we analyze artifacts and ask the question "what is the knowledge that's actually in here?".

It's all a giant process loop of:
analysis -> synthesis -> DSL creation -> DSL processing -> repeat.

[balacij]

Thank you! I completely agree. I was thinking along the same wavelength but I didn't quite have that loop written out, nor the clear definition. That is a very good explanation -- maybe we should put it in the wiki (and elsewhere) too for visibility, if it isn't already there? I think we mainly have examples with code, so this might be another good example.

[JacquesCarette]

I don't think it's there (the wiki) anywhere. I'm not even sure where I would put it. But yes, this is probably worth trying to document.