Missing Information from Data Def Descriptions

[smiths]

I noticed that the generated description for DD:stressDistFac no longer includes text about how J is interpolated from the given data (as done in the original case study). I like how all of the entries from the equation are defined, but there is more to the description than this. I'm assuming this a temporary situation as the Drasil language grows and changes? I noticed that the same thing is done in several of the other data definitions and in some of the other case studies. It is great to de-embed and automate, but we don't want to lose information in the process.

[niazim3]

Yes, due to de-embedding and automation, it does seem that information is being lost. Potential (temporary?) actions:

• Update the constructor currently creating DataDefs (i.e. mkDataDef) to take an extra argument that would just be a Sentence (for now, even though it is "dead knowledge"?) that'd be tacked on to the end of the automatically generated Descriptions.
• Create a new constructor for instances like this, where the description will be passed in and will be output verbatim. Perhaps a pattern can be recognized after such an implementation.

(Although, I'm not sure if the DataDefs generation is being updated to take the additional description information into account (as @szymczdm stated that DataDefs is in the process of being overhauled (comment of commit edaea0c)).)

[niazim3]

Or would it be better to attach the additional information to the actual concept chunk? For example, for strDisFac
, where stressDistFac is
, would be alterred so that there is an additional obtainedFrom parameter that would hold something to the effect of "interpolating data shown in Figure 7".

[smiths]

Thank you for the clarification @niazim3 . I do not know the best way to keep knowledge as we go forward, but I think it is important to keep it, even if it is an "ugly" solution. Once the information is lost, it is hard to get it back. This is why some of the original "manual" case study SRSs do not match. A previous author deleted a section, and then the next author just started from what the previous one left. The information stayed "lost." We should see what @szymczdm and @JacquesCarette recommend for the best way to keep information that doesn't currently fit nicely into the patterns that we've currently identified.

[niazim3]

Below is a rough overview of what is missing from the data definitions in GlassBR (just to see if a pattern can be apparent enough to come up with a solution). It seems that mostly, references to other parts of the document, some definitions, and constraints on some concepts are missing.
DD1 :

• a > b
• h is the true thickness, which is based on the nominal thickness as shown in (ref DD2)
• LDF (ref DD3)
• J (ref DD4)
  DD2:
• h is the MINIMUM thickness
  DD4:
• obtained by interpolating from data shown in (ref figure 7)
• dimensionless load (ref DD7)
• a > b
  DD5:
• a > b
• h (ref DD2)
• tolerable load (ref DD8)
  DD7:
• q (definition?:) is the 3 second equivalent pressure, as given in (ref IM3)
• a > b
• h (ref DD2)
• GTF (ref DD6)
  DD8:
• qHatTol is the tolerable pressure which is obtained from (ref figure 7) using jTol and aspect ratio (a/b) as parameters using interpolation. Calculation of jTol is defined in (ref DD9).
  DD9:
• a > b
• h (ref DD2)
• LDF (ref DD3)
• pbTol is entered by the user

In the case of the constraints though (i.e. the instances where "a > b" is stated), the current output
()
says the same thing as the original pdf
(), so I suppose the wording being different isn't significant enough to be considered "lost information" (especially since "b<a" is a physical constraint)? Or should the constraint be repeated in every DD that a and b are present? @smiths

[smiths]

Great work @niazim3. Your summary of "lost" information was the exact right thing to do. Another item of lost information is the "Source" field in the different definitions. (The source is important information for traceability and it is difficult to recover after the fact.) A pattern that emerges for me is that the information that is left out is connecting to those features of Drasil that have not been implemented. I think the question for @szymczdm and @JacquesCarette is how far we are away from having references and citations fully working. The follow up question for them is: if we cannot get these features working, what is the best way to fake it?

As far as repeating a > b in different places, I'm afraid that this is something I think we need to do. The SRS is not a document that will be read from start to finish like a novel, or even like a journal paper; the SRS is a reference document. It will be referred to with the goal of answering a specific question. That is why I like each of the pieces to be as self-contained and as complete as possible. That is why we repeat the meaning and units of so many of the symbols. This information is in the Table of Symbols, but we don't want people to have to constantly refer to this table. With document generation repeating information like this is essentially free and because of the generation we know that it will be correct. The information that a>b is critical for the definition of a and b, otherwise, there is no way to tell which dimension is the length and which is the width. It is an arbitrary decision, but it is a necessary decision to make the document unambiguous.

[JacquesCarette]

Yes, mkDataDefs needs to be modified to allow such extra information to be un-lost.

We will need to figure out what this 'lost' information really means, so that it is not 'dead'. But first we should make sure it is at least present in the document.

[niazim3]

In commit 723c369, a mkDataDef' constructor was added.
Unfortunately, since the DataDefinitions' descriptions are automatically generated (using descLines and buildDDDescription from Import.hs and toVC from Extract.hs), I don't believe there is currently a way to add the extra information (maybe @szymczdm could clarify please?); I'll add the missing information as sentences to the QDefinitions and keep this issue open for now...

[JacquesCarette]

Hmm, this is another important issue. We definitely need to come back to this one.

[szymczdm]

Yup, we need to discuss this one. I have a feeling this is where Attributes might come into play a bit more, but that depends on the types of information we're trying to keep (and what they "mean").

If we want to display constraints (ie. things like a > b) then we need to know why those particular constraints are important in this context, since we're likely ignoring (not displaying) some other constraints.

I'll also need to think about how to generate the references in the description, since I think there'll be some problems there.

[niazim3]

Update

The overview I commented on Jul 18, 2017 (please see above) still holds. The only thing I want to add is:

• DD9 is also missing that "J_tol is calculated with reference to P_btol"

---

With the addition of a Notes field for the data definitions (done in b032040), a lot of this information can be re-captured. Should this issue be closed after all the missing information is added, even though the Notes field may end up being a temporary solution to the missing information? @szymczdm @JacquesCarette

[JacquesCarette]

There is a lot of different kinds of missing information documented in this one issue. I think it should be splits into many small issues, so that most can be dealt with quickly. Some of them may require more substantial work (like 2. in the update above).

[niazim3]

Thanks @JacquesCarette!

The comment has been updated to include only the type of missing information related to the ones from earlier comments.

Actually adding the missing information back into Drasil will need to be held off until the new DataDefinition type is ready for use (#747).

[niazim3]

Merge of #779 closes this issue.