Finalize Topic Collection Schema

[FlatBallFlyer]

Review use cases for the Topic data structure and planning documents, then finalize the Schema for the Topic collection.

Clarification Added 2/1/24

This is the Curriculum template we are currently using. The topic and related collections should accommodate this information. This shows both EK and Odin resources. Things are organized to allow sections to be visibly collapsed to make the large amount of content more consumable. Google Curriculum Template

[michquinn]

Currently proposed additions are:

• Topic Id
• Outcomes: a list of skills with a slug name, text and level (an enum consisting of the following values: Generalist, Specialist-SRE, Specialist-Data, Specialist-API, Specialist-UX)

[michquinn]

Some thoughts that come to mind reviewing the Topic schema:

• The domain field is obviously taken from EngineerKit, but while it may be useful to preserve this categorization for those topics that we are adopting from there, do we really want to impose this on all other topics that may be added in the future?
• The status property has to be amended as per Topics schema has Partner status property #31
• Skills at it stands corresponds one-to-one to "learning outcomes" in EngineerKit. However, as per the ROADMAP, the system should support the following:
  • Recommending topics to add to an apprentice's curriculum based on their skills (for the Now scope only or also for later on?)

Topics are clearly related to curricula but I don't think we've laid out the exact relationship/use cases anywhere.

[FlatBallFlyer]

Domain: There is nothing to say that a new domain could not be added at any point in the future, those are just the current values. I would actually suggest that we might even want to reduce the domains considerably. The grouping seems a bit arbitrary to me.

Skills: The skills referenced in the Now scope are the self-assessment values provided. If an apprentice has self assessed to possess a skill then resources for that skill should not be recommended. They can still be used, and added to a curriculum but they are not recommended. This is not part of the Topic microservice.

This does imply that we have a self assessment collection somewhere. That is likely a collection we missed, and it is tightly linked to curriculum, so I propose that we add those endpoints to the curriculum API.

Note that the curriculum API will also have a resource review collection, and we may want to add ratings to the resource model, and find a way to update resource ratings out-of-band.

I would also suggest that you evaluate the resource type list. I think that list has way to many values, and we need to reel it in to the values that have meaning in our context. This will require that the scraping script be updated.

We may also want to consider scraping some resources from the Odin Project. You can review the Oden Project Roadmap items in this document, and the Odin Full-Stack Path and then propose an approach for adding those resources (add new domains? - use existing domains - and add a new skill level of "Apprentice Candidate" for Odin resources?)

[FlatBallFlyer]

More clarification on the Domain attribute. Think of it like this, the list of valid values has a very low volatility. Because of the way the API and UI are built, adding a new valid value, and updating the corresponding list in the enums collection, is the only change required. The API only needs to change if there is specific logic tied to the new value, and the UI will get the new valid value added to select lists with no code changes.

[michquinn]

Thinking about the resource type field, it seems to me that rather than using fine-grained classifications such as video/video series/film or article/book/document, it might be more useful to have a few different properties describing important characteristics of the resource. For example:

• Online/Offline: This could be a binary or an array accepting either or both values (such as books that are available on the web and in print)
• Media Type: I was original thinking of a distinction between textual and audiovisual content, but it could also be represented as an array of the following: "text", "video", "audio", and "image". I'm not sure how you would address audio content with subtitles or a transcript, that would probably require another property.
• Primary purpose: Broadly, I think most resources could be described as Instructional/How-to, Explanatory, Evaluatory, and Credentialing. Outside that framework are tools and exercises, and I'd say playing with a tool for learning purposes could constitute an exercise even if unguided.

The free/paid distinction is already captured in another property, and the characteristic of length which separates "video" from "video series" and "film" or "article" from "book" can be captured in the duration property.

[FlatBallFlyer]

I like the thinking - the primary value of the "resource type" attribute is to match it to a learning style. Some people hate watching YouTube, others hate "step-by-step tutorials". Maybe we just call it that - learningStyle. Then if we wanted we could make it a list of styles that are suited to the resource???

Data design in general, a list of strings is better than a list of booleans.

[michquinn]

There would still be at least two dimensions there, since a step-by-step tutorial can take the form of an article or a video, for example.

I suppose you could do something like

learningStyle:
  formats: ["video", "text"]
  resourceTypes: ["explanations", "tests"]

Have to decide on better names but you get the idea

Oh, and video/image could just be "visual", at least for learning style. For resource types that distinction matters

[michquinn]

There seems to be some overlap with the proposed "level" and the existing "isGeneralistSkill" properties. Since the former already includes "generalist" as an option, the latter could be replaced with it.

Edit: I see "level" was proposed to be part of "outcomes". What was the idea behind this property again?

[FlatBallFlyer]

I like the resourceTypes list, and here is my proposal on language. I think some clarification is justified.

• Outcomes should change to Skills, and skills have a level
  • generalist, resident, master, senior, distinguished (for now, names are still a bit up in the air so this is a start)
• Resources should have a list of the skills this resource addresses (map resource to outcomes)
• ResourceType seems to be causing confusion, change the name to learningStyles.
  • The purpose of resourceType is to map resources to a persons learning style.
  • I need to add a learning style to the person schema ;)

If we do this, then I don't think we need the format attribute. If a person has a learning style of "video lecture" and the resource has a learning style of "video lecture" then I think we captured the format, or at least supported the requirement, without having to create a new attribute and logic related to both type and format.

I think it's best to avoid creating things that might require a matrix of functions, or a matrix decision tree. Some times they are needed and important but you should really think about is the complexity required to meet the requirements or are we trying to perfectly capture information that is not needed by any feature but adds both maintenance burden and increases the "technical interest rate" of a piece of code.

[FlatBallFlyer]

The person learning styles feature has a cup-cake, birthday-cake, wedding-cake implementation.

person: 
  learningStyles: 
    exclude: [list of styles]

and later on we can do more with "include", "and or" logic or others, this is just a starter

[GrahamPaasch]

Hi @michquinn . Checking in with you on how to contribute to this issue.

[michquinn]

Hi, @GrahamPaasch. There's no formal process really that I'm aware of, so if you have any suggestions for the schema, I'd be interested in hearing your thoughts 🙂 I hope that answers your question

[michquinn]

@FlatBallFlyer Just to make sure I'm understanding correctly. There seem to be some conflicting/overlapping suggestions so I'm trying to harmonize them

The proposed property topic.outcomes is really just topic.skills but extended. Currently the latter property is an array of strings, which we want to make an array of objects which would look something like this

topic:
  skills:
    - name: Provisioning Cloud Infrastructure
      description: Use Terraform to provision infrastructure with a cloud provider
      level: Resident
      domain: Specialist-SRE
    - name: Clean Code
      description: …
      level: Generalist
      domain: Generalist

Resources then reference these skills

topic:
  resources:
    - name: Terraform in 100 seconds
      type: Explanatory Video
      skills:
        - Provisioning Cloud Infrastructure
    - name: Getting started with Terraform
      type: Instructional Text # you wanted to name this learningStyle here as well?
      skills:
        - Provisioning Cloud Infrastructure

Does that look more or less like what you had in mind?

[FlatBallFlyer]

More or less, I was thinking a slug name (short, no white space) and the list can be discussed with a PR