Kolibri project

This page contains the details of a technical writing project accepted for Season of Docs.

Project summary

Open source organization:
Kolibri
Technical writer:
Danielle V
Project name:
Kolibri Content Workflows
Project length:
Long running (5 months)

Project description

The below proposal was created by conducting research and speaking with the Kolibri mentors. My conversation with the mentors helped me to develop the user personas that I discuss below. In addition, my discussions helped me to come up with the idea regarding a tutorial repository/landing page so that users have the choice regarding which tutorial they want to view for their needs.

Overview

This proposal presents a solution for guiding the various user journeys that an individual can take importing content from their computer into Kolibri Studio, and then from Kolibri Studio into Kolibri. I propose to create a central repository of tutorials. The user will access these tutorials through a landing page. The landing page will provide a table with links to each workflow tutorial and will indicate the type of user that the tutorial could benefit. This way, tutorials will be more personalized to the user’s needs and abilities. A workflow (for example, INSTALL- IMPORT) is demonstrated by multiple lessons. Each lesson contains a video. Videos show a small portion of the workflow and demonstrate individual concepts about how these workflows connect Kolibri applications.

Main Goals

  1. Create a tutorial landing page that helps users decide which workflow best suits their needs. This landing page will be hosted on the Read the Docs platform.

  2. Create individual lessons for the components of each workflow and supplement difficult lessons with exercises.

  3. Create interactive videos for each workflow.

Project Tools

Work will be done using screencasting software. I have experience with Camtasia, but I have also worked with less cost-prohibitive software and freeware. The sample video that is linked here (https://youtu.be/DkMP_VdGslU) was made with Flashback by Blueberry Software, which I currently have a license for. I will create subtitles using Youtube. Tutorial pages will be hosted on Kolibri’s Read the Docs site. Draft work will be completed in Google Docs and I can help with converting text files to Markdown or reStructuredText for the final product.

Timeline

This project will follow the long-term project guidelines (26 weeks total, from 9/2/2019-2/28/2020). I will spend around 10 hours a week completing the goals that are outlined below. In addition to these goals, I will take part in mentor meetings and communication during this time, as needed. I will work with the mentors to determine the best time for this. The timeline is generally split into four-week chunks where I will be creating multiple videos, tutorial pages, and exercises.

Weeks One and Two

Goals:

  • Set up personal device with any websites or accounts needed to access information.
  • Begin to develop structure and more detailed wireframe for the landing page.
  • Discuss with mentors the style for videos, as well as develop a video opening screen template, any filler music for the title and ending screens, and additional information that should be included.
  • Review current documentation and documentation structure to extract links for use in additional resources and tutorial references.

Weeks Three Through Six (Level 1- Beginner Tutorials)

Goals:

  • Develop initial content and lessons for INSTALL-IMPORT/Level 1 workflow. Create video for the download, install, configuration, and import processes. Since the INSTALL-IMPORT functions are the basis for many other workflows, and the most commonly used, a large portion of time will be devoted to getting these tutorials and lessons finalized.
  • Focus on the IMPORT location types and develop a graphic that exemplifies to the user where they can acquire content (public channels that exist in Kolibri Studio) for the landing page.
  • Develop additional videos and content for expansions of INSTALL-IMPORT (UPDATE channel). These expansions could also come in the form of additional resources or links to existing documentation.
  • Work on subtitles for any videos.
  • “Test” videos and ask for feedback from any available resources regarding usability. This would include revisiting the template for videos and solidifying the template for future videos.

Weeks Seven Through Ten (Level 2- Content Uploader)

Goals:

  • Focus on lessons and workflow videos for the Studio Uploader persona.
  • Complete documentation and lessons for UPLOAD-PUBLISH-IMPORT.
  • Develop subtitles for any videos.

Weeks Eleven Through Fourteen (Level 3 - Content “Remixer” and Editor)

Goals:

  • Focus on the following workflows and create tutorial/lesson content: UPLOAD-EDIT-PUBLISH-UPDATE and EDIT-PUBLISH-UPDATE.
  • Develop any subtitles for videos.

Weeks Fifteen Through Eighteen

Goals:

  • As conveyed during my research for this proposal, workflows involving Ricecooker are lower priority (CHEFDEV type). Depending on timing and schedule, I could use this time to create a high-level tutorial that refers to the existing documentation for Ricecooker.

Weeks Nineteen Through Twenty-Two

Goals:

  • Assess any gaps at this time, and test the current flow of all tutorials.
  • Work on finalizing the landing page and begin to link videos together.
  • Work through converting page drafts done in Google Docs to Markdown or reStructuredText, as discussed with mentors.

Weeks Twenty-Three Through Twenty-Five

Goals:

  • Depending on time, finish any final work on low-priority, advanced tutorials.
  • Last minute Read the Docs page editing, file testing, grammar/spelling checking.
  • QA for any links within videos or on other pages.

Week Twenty-Six

Final week for long-running projects. I will work with mentors to wrap up project deliverables and complete any final, required Google documentation.

Tutorial Components

Tutorial Landing Page

Users will access a tutorial landing page on Kolibri’s Read the Docs site, which will provide a brief outline of the various tutorials that are offered for content workflows. The purpose of this page is to give a brief overview of the Kolibri ecosystem as well as provide a graphical view of the various workflows. This gives the user the ability to view the type of workflow that suits their needs, both technically and for their organization's curriculum. Users will have more of an understanding of the options available to them in Kolibri and Kolibri Studio.

Tutorial and Lesson Pages

Each tutorial homepage will give an introduction to the tutorial (made up of multiple lessons), followed by some user goals. Tutorials illustrate a whole workflow and are composed of individual lessons. Each lesson will have a video. Videos will cover an individual part of an overall concept. Each lesson will be kept on an individual page within the tutorial workflow parent page. Lesson pages will have buttons that allow the user to navigate to the previous or next lesson within the tutorial. Very complex concepts can include practice activities.

Videos and Structure

Videos will outline a single concept. Videos will give a direction while performing that action on the screen. An example video can be found here: https://youtu.be/DkMP_VdGslU. This example video shows how to use the Setup Facility wizard.

The video uses callouts and a highlighted cursor to help guide the user through the steps of this single concept. Videos will be hosted on Youtube. If hosted on Youtube, captions will be auto-generated. I will then edit the captions for spelling, grammar, and punctuation. Those captions can then be exported for translations in Amara or another translation tool.

The videos will have a consistent title screen, which I plan to discuss with the mentors in the first couple of weeks. I will also use a consistent callout style (arrows, cursor highlight, boxes), which will be decided together with the mentors in the first couple of weeks.

Example Structures

The simplest workflow, INSTALL-IMPORT, is an entire tutorial. Within that tutorial, are two potential lessons with a video:

  • Downloading, Installing, and Setting Up Your Kolibri Facility
  • Importing Content in Kolibri Studio - Note that this video would be referred to by other workflows

A more advanced tutorial requires multiple sub-lessons with multiple videos. The UPLOAD-EDIT-PUBLISH-UPDATE workflow follows the below structure.

Lesson 1– Uploading Content and Creating Channels in Kolibri Studio

User Goals: At the end of this lesson, you will know how to complete the following actions:

  • Create channels in Kolibri Studio for use in Kolibri. You will know how to use your channel's secret tokens to import your content channel in Kolibri.
  • Create a channel by importing content from existing, public channels in the Studio Library.
  • Create a channel by uploading content from your computer.

Sub-Lesson Videos:

  • Sub-lesson 1 – Create your own channels on Kolibri Studio and import content from existing public channels (Khan Academy, PHET, etc.): Video 1 - Public content channels (viewing PUBLIC channels on Kolibri Studio) Video 2 – Creating a channel Video 3 – Importing content from existing channels Video 4 – Publishing your channel and obtaining the secret token Video 5 – Importing your channel to Kolibri using the secret token
  • Sub-lesson 2—My Documents Content Channel Upload: Video 1 – Uploading files from My Documents Video 2—Creating your own exercises

Lesson 2 – Advanced Editing of Channels in Kolibri Studio

User Goals: At the end of this lesson, you will know how to complete the following actions:

  • Edit content channels in Kolibri Studio
  • Manage content channels in Kolibri Studio

Sub-Lesson Videos:

  • Sub-lesson 1—Editing content by adding exercises, reorganizing folder structure, and collaboration options (1 video)
  • Sub-lesson 2—Using other functions such as deleting/moving content (1 video)

Lesson 3 – Publishing Kolibri Studio Channels for use in Kolibri and Updating Channels

User Goals: At the end of this lesson, you will know how to complete the following actions:

  • Publish a channel in Kolibri Studio and republish after new content is added
  • Update a channel
  • Acquire channel token to import to Kolibri (via a link to the previous video in Lesson 1 that covers this action)

Sub-Lesson Videos:

  • Sub-lesson 1—Publishing updates to a channel

    Video 1: Republishing channel Video 2: Updating channel on Kolibri after adding additional content