Series and series.json - Githubissues

jonmagic commented 10 years ago

Rather than modify our current lesson.json spec I propose we add a new Series model to the app and a new series.json file to include in a repository that links multiple lessons together.

For example, our last series of classes (1, 2, 3, 4, 5) would be represented by this series.json file:

{
  "title": "Intro to Html, Css, and Javascript",
  "lessons": [
    {"lesson": "https://github.com/CoderDojoSF/webdev-lesson-1-html/blob/master/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/webdev-lesson-2-css/blob/master/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/webdev-lesson-3-advanced-css/blob/master/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/webdev-lesson-4-transitions-animations/blob/master/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/webdev-javascript-lesson/blob/master/lesson.json"},
  ]
}

That example has each lesson in a different repository. With this new series.json file you could also organize all of your lessons in the same repository under sub-folders:

{
  "title": "Intro to Html, Css, and Javascript",
  "lessons": [
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/html1/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/css1/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/css2/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/css3/lesson.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/javascript/lesson.json"},
  ]
}

Or you could put all of your lesson files in the root of the repository and just name them differently:

{
  "title": "Intro to Html, Css, and Javascript",
  "lessons": [
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/html1.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/css1.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/css2.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/css3.json"},
    {"lesson": "https://github.com/CoderDojoSF/intro-html-css-javascript/blob/master/javascript.json"},
  ]
}

I propose this is the direction we go for adding support for a series of lessons. Here are the issues we'd need to create to track the work:

[ ] Add Series model to the application and a SeriesLessons join model so we can do a many to many relationship.
[ ] Add a SeriesImporter class for processing series imports.
[ ] Update the UI to focus on series of lessons instead of individual lessons.
[ ] Add documentation for the new series.json spec.
[ ] Update the admin section to include a series.json builder.
[ ] Add series.json files to repositories for each series we've already done.

So what do folks think? /cc @cameronmcefee @mikefowler @kbsail

cameronmcefee commented 10 years ago

Seems potentially reasonable to me. Does the series.json live in every repo if the lessons are distributed?

mikefowler commented 10 years ago

This approach seems good to me. Given @cameronmcefee's point about multiple series.json files, maybe this would dictate that in the future we create series lessons in a single repository to reduce duplication.

jonmagic commented 10 years ago

It would only need to live in one repo, either one of the lessons or a series description repo. But yeah, my pref would be for future series to include all lessons in a single repo.

cameronmcefee commented 10 years ago

It would only need to live in one repo

I think the thing that I don't quite care for is that in the subsequent repos it wouldn't be clear that it was part of a series, though I suppose that could be solved outside of the json file, with titles and whatnot.

KartikTalwar commented 10 years ago

Sorry for jumping in late - If the series.json lives in one repo (lets say the first session) we can rename separate git repos accordingly like @cameronmcefee said. But if the goal is to also include all lessons in a single repo, I wanted to ask if you guys think publishing new lessons would be affected.

I've seen in the past the lesson being a private repo that the mentor would work on and it would become a public repo the night before or morning of. Would it make that big of a difference if people can see the lesson being developed/ready a few days before (even on a different branch) the session?

jonmagic commented 10 years ago

@KartikTalwar hmm, I hadn't heard of keeping lesson repos private until launch, I just figured they were always public (our lesson.json and this app assumes that since it has to import the lesson.json file in order to create the event).

I'd prefer to "encourage" people to develop their classes in the open I guess, otherwise the lesson metadata and event state will have to originate in this app instead of the lesson repo.

KartikTalwar commented 10 years ago

@jonmagic makes sense, and I agree. I was just curious to know if peeking at the next lesson affects the experience in any way (for students).

cameronmcefee commented 10 years ago

I think it's probably fine if it's public during development. We could always have a published flag in the lesson.json file that determines whether it shows up on the site. Then we can work to reinforce that only lessons on the site are complete lessons.

mikefowler commented 10 years ago

:+1: for encouraging planning lessons in the open. @cameronmcefee's suggestion for a published flag seems valuable. As to students peeking at the lesson, I don't see any negatives, but I also don't think it would happen very frequently.

KartikTalwar commented 10 years ago

Sounds good, just wanted to ask :smile:

jonmagic commented 10 years ago

We could always have a published flag in the lesson.json file that determines whether it shows up on the site. Then we can work to reinforce that only lessons on the site are complete lessons.

Here's the thing, without a lesson there is no event. We would need to divorce the two concepts in the dojo app in order to show an event but hide the lesson if it hasn't been "published" yet.

I see no harm in students or parents having a link to the lesson repository before it's finished, seeing someone build a lesson is educational in itself.

I'm :-1: on a published flag in lesson.json, let's keep it simple for the time being and add features later if/when we run into problems.

CoderDojoGitHub / our-dojo

Series and series.json #33