search

JacquesCarette / Drasil

Generate all the things (focusing on research software)
https://jacquescarette.github.io/Drasil
BSD 2-Clause "Simplified" License
141 stars 26 forks source link

Adding Documentation for Chunks, Types, Classes, and Instances #2679

Open Ant13731 opened 3 years ago

Ant13731 commented 3 years ago

The Wiki should have some articles detailing Chunks, types, classes, instances, and how they are used in Drasil. We should also make a list of readings (perhaps on the home page) for new contributors. This can include Learn You a Haskell for Great Good, Contributor's guide, New workspace setup, git2know, etc.

From Dr. Carette:

What should an “Introduction to Drasil” for new developers should look like. In other words, an ordered reading list of materials, most likely including some materials that currently do not exist but users currently have to figure out “the hard way”. It was my plan to start documenting the ideas contained in 1) chunks, 2) the classes, and 3) their relation (via instances). These are indeed quite core, and not really explained anywhere (yet).

This issue is to keep track of the progress for this documentation:

From #2612 and may be the same as above,

Perhaps the ideas discussed about the different Theories, Models, and Definitions should each have their own page. I know their design is currently being discussed in #2599, so should we wait before writing a Wiki page about it?

JacquesCarette commented 3 years ago

So I was kind of imagining that I would have to write this documentation. But I'd be quite happy to "share the burden"! So yes, please do start such pages, but start small, and let's discuss. I don't want you to spend hours writing things that are going in a completely different direction than I was expecting.

Ant13731 commented 3 years ago

Okay, sounds good. I've already started a little bit on chunks and information encoding (I'm not really sure if its all correct though), but I tried to add a little bit of how I understand it. It's not really organized/edited properly after the Chunks section, but I'll leave the link here. So far, I've just tried to take the ideas examined in the written papers (I took a diagram too from the one given in #2220) and gather them into one spot.

JacquesCarette commented 3 years ago

Sorry for taking so long to review this.

Meta comment: in general, I much prefer smaller wiki pages, with lots of links, to large ones that cover multiple topics. So this page should be split into pieces. I'll do that (now). I'll come back to this issue when I have comments about things that I'd like you to fix.

JacquesCarette commented 3 years ago

So one of the most important things that needs to be in the Chunks page is a list of all of the chunks along with a 1-liner explanation of what that chunk is for.

JacquesCarette commented 3 years ago

Also, please carefully read the new Information Encoding as it tries to express the high-level idea of what's going on.

Ant13731 commented 3 years ago

So one of the most important things that needs to be in the Chunks page is a list of all of the chunks along with a 1-liner explanation of what that chunk is for.

Would this be something that should go in the Chunks wiki or the Haddock docs (for easier maintenance)?

Ant13731 commented 3 years ago

While going over some of the different chunks in detail, I noticed that CommonConcept does pretty much the same thing as ConceptChunk, aside from the abbreviation being String instead of a Maybe String. Its only really being used in a few places, so should CommonConcept be removed completely?

Also, CI and IdeaDict create chunks in different orders. IdeaDict seems to build off of NamedChunk by holding a possible abbreviation in addition to a term and UID. So while CI would be expected to do a similar thing (i.e., contain a UID, term, and abbreviation), it also adds domain tagging. This becomes confusing when we start making ConceptChunks because we expect the only domain tagging to be at the concept level of chunks, rather than at the idea level. In other words, ConceptChunks and CI both contain domain tags, but they have no relation to each other when it seems like they should. Perhaps IdeaDict could go inside CI, and CI into ConceptChunk, to make the progression of adding one thing at a time more fluent. So the order of creating a chunk would be:

building a chunk from UID to definition:
UID -> term (NP) -> abbreviation (String) -> domain ([UID]) -> definition (Sentence)
                \                       \                \                      \
                 -> NamedChunk           -> IdeaDict      -> CI                  -> ConceptChunk

The only reason this couldn't be implemented immediately is because IdeaDict only takes a Maybe String while CI takes a String for the abbreviation, but #2677 should resolve that

Also, I noticed that QDefinition has the type:

data QDefinition = EC
  { _qua    :: QuantityDict
  , _defn'  :: Sentence
  , _inputs :: [UID]
  , _equat  :: Expr
  , cd      :: [UID]
  }

when (I think) it could be reduced to:

data QDefinition = EC
  { _qua    :: DefinedQuantityDict
  , _inputs :: [UID]
  , _equat  :: Expr
  }
Ant13731 commented 3 years ago

I've also noticed that UnitaryConceptDict and UnitalChunk have the exact same fields, with the only difference being the stage at which the definition and domain are added.

JacquesCarette commented 3 years ago
Ant13731 commented 3 years ago

wiki or Haddock: in theory, both. At the very least, a list (w/ links) in the wiki, pointing to the Haddock?

I've been working on a table in the wiki that should have all of the chunks in Drasil as well as a new PR that adds examples of chunks to the haddock docs. Right now, its ordered by appearance in the program files but I think it would be good to order by hierarchy to some extent.

JacquesCarette commented 3 years ago

Yes, absolutely, ordering by hierarchy, as much as feasible, would be much better.