Import Lesson - Is it Possible?

Some time ago, Greg Wilson wrote about the idea of import lessons. This is food for thought about it.

Version Control and Possibility to Fork Lessons

For individual lesson we should use a modern distribute version control system like Git or Mercurial.

The problem is what use to deal with the collection of lessons when import each one. We can think in use Git Submodule or Git Subtree but from my experience the better approach is use a tool on top of Git or Mercurial like git-repo. This approach will avoid the user learn the complexity of Git Submodule and let the user choose the version control system more suitable to he/she needs.

Dependencies

For package management system is easy to resolve dependencies since it envolves only know two informations: (1) the name of required package and (2) the version of it. For educational resources this can be much more complex but for now lets keep simple and say that to resolve the dependencies of one lessons you only need to know three informations: (1) the protocol to use when download the required lesson, (2) the URL of the required lesson and (3) the version of it.

Format

The format of the lessons can also be a problem. After think a little about it the best solution that I find was request that every lessons be available as HTML or inform a rule to build it as HTML. The reasons to use HTML are:

  • is an open format;
  • is the format used at the Web (and EPUB);
  • for many others formats exist a tool to convert it into HTML.

Metadata and Manifest

To import lessons we will need that lessons have a few metadata and the format to store it should be JSON. The minimal list of metadata that I could list was:

Authors

Ordered list of following informations about the authors.

Name
Full name of the author.
Contact
Email of the author.
Title
Title of the lesson.
Language
Language of the lesson.
License
Lesson must be under an copyleft license.
URL
URL where the lesson is available or more information can be found.
Require

Unordered list of following informations about the required lessons.

Name
String used as reference at NAV field.
Protocol
Protocol to be used to download the lesson. Git, Mercurial or other version control system.
Remote
URL where the lesson is available to download.
Revision
Revision required.
Protocol
Protocol to be used to download this lesson. Git, Mercurial or other version control system.
Remote
URL where this lesson is available to download.
Build
Command used to build the lesson to HTML.
NAV

Ordered list of following information about the lessons that are part of this one.

Name
The path of one file of this lesson or Name of a required lesson.

Lesson Example

Let say that John Doe wrote a lesson about the solar system that the only file is index.html and use git to version it. The possible JSON is

{
    "authors": [{"name": "John Doe", "contact": "john.doe@mail.com"}],
    "title": "Solar System",
    "language": "en",
    "license": "cc-by",
    "url": "http://john-doe.github.io/solar-system",
    "require": [],
    "protocol": "git",
    "remote": "http://github.com/john-doe/solar-system",
    "nav": [{"name": "index.html"}]
}

Collection Example

Let say that Jane Doe is going to create a collection from Software Carpentry lessons for a Git course. The possible JSON is

{
    "authors": [{"name": Jane Doe", "contact":jane.doe@mail.com"}],
    "title": "Jane's Git Course",
    "language": "en",
    "license": "cc-by",
    "url": "http://jane-doe.github.io/git-course",
    "require":[
        {"name": "shell-filedir",
         "protocol": "git",
         "remote": "http://github.com/swcarpentry/shell-filedir",
         "revision": "master"},
        {"name": "shell-create",
         "protocol": "git",
         "remote": "http://github.com/swcarpentry/shell-create",
         "revision": "master"},
        {"name": "git-backup",
         "protocol": "git",
         "remote": "http://github.com/swcarpentry/git-backup",
         "revision": "master"},
        {"name": "git-collab",
         "protocol": "git",
         "remote": "http://github.com/swcarpentry/git-collab",
         "revision": "master"},
        {"name": "git-conflict",
         "protocol": "git",
         "remote": "http://github.com/swcarpentry/git-conflict",
         "revision": "master"}
    ],
    "protocol": "git",
    "remote": "http://github.com/jane-doe/git-course",
    "nav": [
        {"name": "index.html"},
        {"name": "shell-filedir"},
        {"name": "shell-create"},
        {"name": "git-backup"},
        {"name": "git-collab"},
        {"name": "git-conflict"},
        {"name": "exercises.html"}
    ]
}

Prototype and Mozilla Science Lab Multi-Site Sprint

For the sprint that Mozilla Science Lab will run on July 22-23 I believe that we can implement a tool to import lessons following the suggestion above and test it to handle Software Carpentry’s shell, git and mercurial lessons.

Update

One nice discussion happened at the Open Education mail list from Open Knowledge.

Rémi setup one repository to be used at Mozilla Science Lab Sprint.