Coach Resource Discovery

[rtibbles]

What is this feature? What is the problem that it is solving?

This feature is the last part of the existing, planned work for integrating search that uses metadata into Studio and Kolibri.

The initial work made it possible for metadata to be added in Studio, and from there, we added features that helped learners use this metadata to search and filter resources. For the self-directed learner in particular, discoverability was very important. This was a key part of 0.15's hybrid learning work, which focused on students learning at home, without a facilitator. Metadata search in Learn also supported adding the Kolibri App to the open testing track on the Play Store in 0.16. Kolibri 0.16 also focused on self-directed learning and enabled remote content browsing of the Kolibri Content Library (Studio) and neighboring Kolibris on the same LAN.

Now, we are turning our attention to the Coach experience, using this additional metadata to help with resource discoverability during both lesson and quiz planning.

On the user side - there should be a consistent, smooth user experience of metadata search that makes it easier for Coaches to quickly find relevant resources they need for lessons and quizzes, and explore potentially relevant resources they may not have considered before.

On the technical side - the feature abstracts the metadata search experience in Learn, moves it to kolibri-common, and then integrates these common elements (composables, components) into both Learn and Coach.

Community feedback that has helped shaped the problem definition and feature

Based on the three February 2018 content discoverability workshops in Kakuma and April/May 2018 testing and modification sessions on Studio, it seems apparent that users looking for materials on Kolibri (wherever a search interface appears) and Studio (when adding and browsing content) are missing content that could be potentially useful to them, as well as encountering content which does not meet their needs and becoming frustrated with the entire process. This inhibits their ability to move about the content library with ease, truly envision the wider possibilities of the heterogenous curriculum, and spend the time they have for lesson planning on creative pedagogical engagement with content rather than prosaic relevance-checking.

Specific observations included:

• Preference to use category filters and free-browsing over keyword search, which was ranked as the fastest but not the most useful or educational search method.
• Difficulty conceptualizing and iterating upon more creative keywords when one search did not yield desired results.
• Becoming overwhelmed by the number of search results and choosing the first few content sources in sight.
• Desire to know things about content at searching stage which platform does not convey, and which require too much user overhead to check oneself.

IDOC teachers named subject, language, and age range as metadata it was most important for them to see on Kolibri channel cards...the mixing of these diverse audience indicators within single channels and even single subtopics would make the browsing experience overwhelming and frustrating.
These categories have previously come up as the most critical for users in filtering and creating mental elimination schema to search for content

How do we know this feature is successful?

We know this feature is successful if we hear feedback about an improved experience for coaches regarding resource discoverability. This could be things like:

• planning lessons and quizzes is faster than before
• it is easier to find relevant resources
• coaches experience of lesson and quiz creation and management is less frustrating and overwhelming
• it's possible to discover relevant resources that the coach might have not previously thought to include (i.e. content from an available channel that the coach was less familiar with)
• it's easier to mix and match resources from various sources to create a lesson or quiz

Are there any assumptions or constraints we are operating under?

In terms of the specific application in Coach, the main technical and design constraint is that we want to have the same experience as in Learn, reusing what we have to avoid (potentially confusing) parallel experiences and/or parallel implementations and tech debt.

Assumptions, constraints, and decisions that shaped this work overall (the approach to metadata search, rather than the specific implementation in coach), include the following description of metadata value that came out of an early design sprint related to this work:

Contextual metadata are high-value metadata. They’re more important than others in the discovery of content for curriculum, so less of them will suffice. The categories of contextual metadata we identified:

Classroom Constraints

1. Do I have the necessary resources to use it (ie need an overhead projector)?
2. Do I have enough time to use it?

Modality of Usage

1. What am I using it for?
2. What kind of learning objective do I have? (Not what is it!)
3. What are some ways in which I could use it?

Comprehensibility

1. Who can and can’t understand this?
2. Who could understand this and with what kind of work?

What are technical approaches, risks, or pitfalls that have already been discussed during planning?

• Reuse, reuse, reuse existing code, components, designs, and patterns
• Components for the Search/Filter UI should be as consistent as possible, although they may require some configurability (i.e. hiding the "Learning Activities" filter option when searching for quiz exercises)
• Use the useSearch composable, as it exists in Learn, as much as possible. Deviating from this is probably either a specification error, or an implementation error! When in doubt, ask Richard for clarification around expected behavior as he was the original implementor on the composable and search experience in Learn.
• Because the composable uses Provide/Inject to reduce prop drilling, the component hierarchy needs to be maintained (or if changed, this should be done with consideration and discussion - not just trying to make the components seem more "organized" or prettier). For example, <SearchFiltersPanel> uses injectSearch() and this requires useSearch() in the component ancestry
• useSearch() is used (i.e. invoked in the setup function of the component) in LibraryPage/index.vue, which is not the same as places it is imported
• The SearchFiltersPanel can be more rationally structured and somewhat refactored as part of this work, but it should be done with care. Right now the Category modals are children - we could consider them being moved out. The clearable Learning Activity Chips should also be migrated along with the other UI components.
• useContentNodeProgress should be handled via dependency injection, as it is only relevant in Learn. Creating a Learn-specific composable to handle dependency injection would likely be a good strategy
• The baseUrl is also only relevant in Learn (where we have remote browsing), because coaches should not be browsing remote libraries for potential resources and creating lessons and quizzes with remote resources that may not be available in the future.
• The new KCard and KCardGrid should be used
• The SidePanel component may need to be updated to be more flexible. Currently we are only using a few set widths, but we may continue to extend the possible widths of the component, and therefore, a small refactor to better accommodate variable widths may be useful if the component begins to feel unwieldy with the changes required for the updates in this project.

Acceptance criteria/definition of done for the feature

• useSearch composables and related dependencies have been moved into kolibri-common
• UX components have been moved into kolibri-common
• Components that use a grid system, such as search results, should be refactored to use KCard and KGrid , and this should result in improved accessibility (n.b. KCard is not the end product for the card that will be used, but other cards may need to be built using it)
• An updated "Coach Resource List Card" (name very tbd) should be created on top of KCard to reflect the updated layout, information architecture, and styles of the cards that are used in the spec
• A coach can search and filter within channel resources within lesson creation/management and quiz creation/management

Stretch goals:

• A coach can preview exercises/quizzes that they have selected in a full screen viewer

What is out of scope?

• We are not refactoring logic in any significant way - we are just moving things
• Tag search

What is the timeline of this project?

• Some design work was scoped under 0.15
• Finalizing design work, and community feedback sessions with Lewa and S2S will happen during Q1/Q2
• Technical planning will begin during Q1 and continue into Q2
• Dev work will take place during Q3 and Q4
• Feature completion by end of Q4 2024

Product Issues

Preview Give feedback

1. Product Issue: New navigation and information architecture supports improved user experience #12710
   +0
2. Product Issue: Iterative improvements to EQM: Question selection #12916
   +0
3. Product Issue: Robust metadata search is available in Coach when creating and managing lessons #12917
   +0

Prerequisites

Preview Give feedback

1. Enhanced quiz management #10802
   Epic +1
2. Create KCard Component kolibri-design-system#445
   Epic category: docs content category: library +3
3. Determine the order and criteria by which we filter the "most important" metadata to display on the card, and create a source of truth for this ordering
4. Determine routes structure and route names for the side panel navigation in both quizzes and lessons, based on 0.17 EQM patterns
5. Create temporary routes path where changes will be built for lesson creation and editing #12622
   APP: Coach DEV: frontend P0 - critical +3
   
6. Create searchAndFilterStrings.js file in kolibri-common, to handle new strings as well as migrated commonLearn strings

Migration of useSearch() to kolibri-common, composables refactor

Preview Give feedback

1. Copy useSearch() into kolibri-common as baseUseSearch() #12516
   +0
   
2. In Learn, update useSearch() to extend baseUseSearch() #12517
   1 of 1
   +0
   
3. Make searching scoped within topics, based on the current folder #12608
   +0
4. Update Learn so that searching and filtering UI references new kolibri-common components, and delete Learn-specific components #12518
   +0

Learn and Search component updates: refactors and migrations

Preview Give feedback

1. Add <SearchFiltersPanel> and children into kolibri-common #12519
   DEV: frontend P0 - critical +2
   
2. Add <SearchResultsGrid> into kolibri-common and move relevant related components (such as <LearningActivityChip>) #12520
   +0
3. Update <SearchFiltersPanel> to accomodate differences in display between Learn and Coach, and within Coach, to manage quizzes (i.e. no Learning Activity types) vs. lesson resources #12521
   +0
   
4. Ensure grid "view more" and "pagination" behaviors that are present in learn are moved along with the components, and that they are reusable with them #12522
   +0
5. Update Accordion components for extensibility and flexibility #12676
   +0
   
6. Clean up remaining accordion component uses and old code

Cards and Grids

Preview Give feedback

1. Refactor <SearchResultsGrid> to use new <KCardGrid> and updated card built on <KCard> #12695
   +0
   
2. Create MVP Coach "channel card" using <KCard> to use in the resource management side panel #12528
   +0
3. Implement conditionalized and prioritized metadata label display on refactored cards #12526
   +0
   
4. Write helper function(s) to manage display of metadata tags following prioritization criteria #12525
   P0 - critical +1
   
5. Upgrade places utilizing KCard from beta to its final API #12688
   +0
6. upgrade KDS to rc7
7. Annotate ordered channel metadata during content annotation #12880
   P0 - critical +1
   
8. Refactor the Learn search results grid to use the new KCardGrid and KCard #12873
   +0
   

Quizzes - updates to 0.17 EQM question replacement workflow

Preview Give feedback

1. Create a "Selected Resources" preview view that shows currently selected resources and questions
2. In Coach, update the quiz creation and management experience to use the kolibri-common useBaseSearch() #12624
   3 of 4
   +0
   
3. Update the "Select a practice quiz" workflow

Lessons - integration of useSearch and alignment to quiz UI

Preview Give feedback

1. Refactor ContentCardList to use the new KCardGrid and the AccessibleResourceCard and AccessibleFolderCard #12732
   +0
2. Create a minimal version composable for managing resource selection panel state #12731
   +0
   
3. Add the initial "Manage Resources" Side panel workflow #12786
   APP: Coach DEV: frontend P0 - critical +3
   
4. Create the basic layout display for "resources currently in lesson" #12787
   APP: Coach DEV: frontend P0 - critical +3
   
5. Integrate Search Filters related components into lessons workflow #12788
   APP: Coach DEV: frontend P0 - critical TODO: needs decisions +4
   
6. Create question preview display for practice resources #12789
   +0
7. Update <ResourceSelection /> so that can it can be used in lessons, without breaking the current quiz workflow #12790
   APP: Coach DEV: frontend P0 - critical +3
   

Information Architecture - new coach page structure

Preview Give feedback

1. Update the Plan > Lessons landing page to align with new information architecture #12690
   +0
   
2. Update the Plan > Lesson Summary page to reflect both planning and report elements #12707
   +0
   
3. Update the Plan > Quizzes landing page to align with new information architecture #12670
   +0
   
4. Update the Quiz Summary page to replace the "preview" section with the learner report and difficult questions #12671
   +0
   
5. Update views to create new "Groups" pages #12678
   +0
   
6. Update Learner Reports pages to have additional information and updated UI #12679
   +0
   
7. Implement "Filter by Groups" functionality with new information architecture page structure #12706
   APP: Coach P0 - critical +2
   
8. Update mainline navigation and remove unused components and files after "landing pages" are merged #12729
   +0
   
9. Ensure all export as CSV reports are working #12734
   APP: Coach P0 - critical +2
   
10. Remove "Activity" tab from learner view #12733
    DEV: frontend P1 - important +2
    

Additional design fixes and improvements

Preview Give feedback

1. Allow coaches to choose when a quiz report should become visible to learner #12902
   +0
2. Update quiz assignment workflow to use side panel UI #12901
   APP: Coach P1 - important +2
   

Resources

• Figma
• Document summarizing findings and feedback from Kakuma experts (2018)
• Document summarizing feedback from ICOD regarding most important metadata
• Cross-Product Metadata needs meeting notes (2020)
• Metadata presentation - past design sprint (2019)

Previously existing bugs that should be resolved by this work

Preview Give feedback

1. App crashed after initiating a search in "Manage Resources" section and "Learn" page #7639
   APP: Coach bug +2
2. Add pagination to Lesson and Quiz resource navigation to handle unnecessarily large topics #7637
   TODO: needs clarification +1
3. User can search for content within a channel, but not within a topic #7635
   APP: Coach TAG: ux update +2
4. The search results list updates before reloading the page #7590
   TAG: ux update +1
5. Search result page includes items from the other channel #7589
   APP: Coach TAG: ux update TODO: needs decisions design +4
6. When navigating resources for quiz/lesson-creation, unchanging elements in UI flash in and out #7558
   APP: Coach DEV: frontend TAG: ux update +3
7. Update coach lesson creation bookmarking to match changes in quizzes #8822
   P1 - important TAG: tech update / debt +2
   
8. Coach Bookmarks Follow-Up #8384
   P1 - important +1
9. Selecting bookmarks within lesson management #8211
   P1 - important +1
10. Coach cards - channels, topics, resources, lessons, (channel) quizzes #7880
    design +1