Investigate and Document the Intent of each Chunk

[samm82]

This issue will be worked on in a wiki page.

---

While there is some documentation in the wiki and through Haddock surrounding the "what" of each chunk in Drasil, there isn't much "why", which can lead to some chunk types being chosen for a use case where they aren't the best fit. We want to remedy this by documenting what each chunk semantically represents (at a deeper level than just what it contains, while still being brief!) along with examples of code to actually see how this all works together.

For example, DefinedQuantityDict is defined by the Haddock documentation as "the combination of a Concept and a Quantity. Contains a ConceptChunk, a Symbol dependent on Stage, a Space, and maybe a UnitDefn. Used when we want to assign a quantity to a concept. Includes the space, symbol, and units for that quantity." However, this description never explains why we would want to assign a quantity to a concept.

---

This was motivated by #2704 in an attempt to find the rationale behind creating DefinedQuantityDicts in the first place, and will provide some background on #1658 to see why certain chunks are used (and why we often have to merge a Quantity and Concept into a DefinedQuantityDict).

[smiths]

This issue sounds good to me @samm82.

[JacquesCarette]

Looks good to me as well.

What I'm expecting will be needed is to first document the "parts" that go into each chunk (description, unit, space, etc) and their rationale. The chunks are then unions of parts. Chunks are then naturally partially ordered by inclusion of parts. Parts themselves are also partially ordered - it makes no sense to have a unit if there is no quantity.

[peter-michalski]

I appreciate that you made this issue @samm82 . The "why" surrounding Drasil's current chunks is something that I too will need to understand and critique.

When I do look into this myself I am planning on a review of previous issues, and re-reads of Drasil papers. I do wonder how much of the background information (and conversations) that led to the decisions to create some of the current chunks is tacit knowledge though.

[JacquesCarette]

Lots and lots was only discussed in meetings. There are bits and pieces on the wiki. However, I don't think it is so hard to reconstruct, as we did try to give things meaningful names (to record fields), so some of our intent is recorded. The chunk names themselves are sometimes good, sometimes bad.

[peter-michalski]

I thought of this issue when looking at MUChunk. It would be nice if deprecated chunks, their usage, rationale, and rationale for deprecating them, were also documented in the wiki, or in another artifact. That way developers could better understand how and why Drasil encoding has progressed to where it is today. Perhaps a time might come when developers need to resurrect deprecated chunks, or at least reference their documentation to avoid, or improve, going down an already explored path. It might be tedious to do this retroactively, and it might not be feasible to remember/find all deprecated chunks, but once the current chunks are documented it would be great if we avoid removing them from the documentation if they are ever deprecated, and instead tag them and add design decision rationale for deprecation.

Design documentation that includes deprecated data structures, and details the rationale, seems like it could be quite useful in domains that require developing a knowledge encoding.

[JacquesCarette]

I agree. But first, we need to document our basic design!