Public Lesson and Event Site

[jonmagic]

I imagine an extremely simple user interface with just three pages, a home page, lessons page, and individual lesson page. I think the app should rely heavily on email to communicate with registrants. Below I explain each page and the workflow of each page and each email.

There is a bit of logic to the lesson page, so be sure to read through it carefully.

Home page

• Describes what we're doing and who we are. I just stole the blurb from our EventBrite events for now.
• Shows an upcoming event and lesson preview if one exists OR the last lesson preview if one does not exist.
• Has a link to view a list of all of the lessons on the lessons page.
• Has a signup form for a Upcoming CoderDojo Events Newsletter. The form just has an email field and submit button.

  Lessons page

• Link back to homepage (app heading will probably just be a link back to the home page).
• Shows a list of all lessons, no event data here, just previews and links for all of the lessons.

  Lesson page

• Lesson preview which is an image (or intro video), lesson title, and lesson summary.
• If the lesson has an upcoming event for it:
  • Teacher information, their name, where they work, maybe a gravatar.
  • The event date and location will be shown.
  • AND if registration is open there will be an event signup form. This form will just have an email field, number of students they will be bringing, and a submit button.
• If the lesson has an upcoming event but registration is full the signup form will be replaced with an explanation.
• If the lesson has an upcoming event but registration has not opened there will be an form to signup to be notified when the event registration opens.
• If there is no upcoming event no event information will be shown on the lesson.

  Emails

  Upcoming event newsletter

The form to signup for the upcoming event newsletter will be on the home page. I will probably just use a newsletter service to handle this so I don't have to deal with subscribe/unsubscribe crap.

This email will get sent out as soon as an upcoming events registration opens and will contain a link to the lesson so they can go there and signup using their email address and specifying the number of students they want to register.

Notify me when event registration opens

The form to signup to be notified when a specific events registration opens will be located on the lesson page for a lesson with an upcoming event where registration has not yet opened.

This email will contain information about the lesson and a link to the lesson so they can signup for the event using their email and specifying the number of students they want to register.

Registered at last event email

There is not form to signup for this email. You are automatically subscribed to it when you register for an event. The next time there is an event this email will go out to the previous registrants 24 hours prior to the event registration opening.

The email will contain a preview of the lesson plus a link to signup for the event early.

We will just assume they are signing up the same number of students, so when they click the link it will sign them up and redirect them to the lesson.

If the event had room we will flash a message explaining that they have been registered. If the class is already full we'll flash a message explaining that.

This email only goes out to the registrants from the last event and not any events before the last event.

Register for event email

The form for this is on the lesson page for a lesson with an upcoming event where registration is open.

The email will contain a link to confirm that they want to register for the event. I hope this will keep spam down.

When they click the link it will attempt to register them for the event and then redirect them to the lesson page.

If they registered successfully we will flash a message explaining that. If for some reason the class is full now (if they didn't click confirm in a decent amount of time) then we will flash a message explaining it is full.

Creating Lessons and Events

There is no lesson or event management interface, everything happens automatically. The app either scans the repositories in the CoderDojoSF organization on GitHub on a set interval, or if there is a webhook available we'll just use that to notify the app of new or updated repositories.

Either way the app looks for a lesson.json file in each repository and if one exists it will read it, see if the lesson already exists in the database and if not it will create it.

Example lesson.json:

{
  title: "Animations in JavaScript",
  summary: "Build animations in the web browser using javascript and the D3.js library.",
  events: [
    {
      location: "GitHub 548 4th St San Francisco CA 94107",
      date: "Sat Apr 20 2013 10:00:00 GMT-0700 (PDT)",
      length_in_hours: 2,
      teachers_github_username: "jonmagic"
    }
  ]
}

If the lesson.json events array has an event in it then the app will look to see if the event already exists and if not it will create it.

Using this automatic import the first iteration of the app doesn't need a management interface, which I really like.

Note: This is just the first rough draft of the lesson.json schema and we can of course change it based on our needs. It doesn't feel quite right to me yet, but it is a start.

[jonmagic]

From @cameronmcefee on the original gist:

I think I'm on board with most of this. I'm starting to think I want to strike the whole alumni ticket thing. Some of the other dojos have a system of "the only way to guarantee a spot is to volunteer" system (more here) that I'd kind of like to try exploring. Especially if we start going toward the multi-week session plan, the alumni thing becomes more of a hinderance to getting new people involved.

I like this direction for the lesson.json file. Not sure if we should add an array for authors or just source contributors and list those. That basically equates to the same thing.

How do you feel like we should handle lesson.json formatting errors? My first thought would be that if it can't be loaded, the lesson just doesn't show up, or the app shows some sort of indication (not sure where without an admin mode) that there are lessons it wants to but can't add.

It might also be nice to have some sort of app (omg another one) where you logo in with your GitHub id, fill out a form, including picking your lesson repo, and then the app commits the lesson.json file for you.

[jonmagic]

I think I'm on board with most of this. I'm starting to think I want to strike the whole alumni ticket thing. Some of the other dojos have a system of "the only way to guarantee a spot is to volunteer" system (more here) that I'd kind of like to try exploring. Especially if we start going toward the multi-week session plan, the alumni thing becomes more of a hinderance to getting new people involved.

@cameronmcefee awesome, I'll tweak this idea to not include the alumni stuff.

I like this direction for the lesson.json file. Not sure if we should add an array for authors or just source contributors and list those. That basically equates to the same thing.

I'll keep tweaking the lesson.json, hadn't thought about the fact that there might be multiple authors/contributors.

How do you feel like we should handle lesson.json formatting errors? My first thought would be that if it can't be loaded, the lesson just doesn't show up, or the app shows some sort of indication (not sure where without an admin mode) that there are lessons it wants to but can't add.

I think your last idea, to have the app generate the lesson.json for you, is probably the easiest way to avoid mistakes. But if there is a formatting error we can just shoot an email to the repository committers telling them the app was unable to import it.

[jonmagic]

This app already has auth for CoderDojoSF organization members built into it, so I'll build the lesson.json generator directly into this app rather than spin up a new one.

[cameronmcefee]

Sweet. I kind of like that this app is beginning to sound like a one stop shop for a dojo. It sounds like it basically just runs everything through GitHub and shows you different stuff depending on your context (Authed to GitHub? here's the mentor stuff. Not authed? Here's the kid friendly lessons.)

[jonmagic]

Exactly.

On Tuesday, April 23, 2013 at 3:26 PM, Cameron McEfee wrote:

Sweet. I kind of like that this app is beginning to sound like a one stop shop for a dojo. It sounds like it basically just runs everything through GitHub and shows you different stuff depending on your context (Authed to GitHub? here's the mentor stuff. Not authed? Here's the kid friendly lessons.)

— Reply to this email directly or view it on GitHub (https://github.com/CoderDojoSF/event-app/issues/9#issuecomment-16890769).

[brntbeer]

I'm late to the game on replying to this, please accept my apologies!

I really like the idea of one single place for an app (as mentioned in other issues and in conversations in person).

Do we see this competing or helping with zen.coderdojo.com or this is just an alternative if you want to use more of a GitHub workflow to your lesson (storing your lessons on GitHub, managing mentors this way, etc)

[jonmagic]

This is an alternative. I looked at our needs and our workflows, and then designed and built something that fits that framework.

It looks ugly now so I hope that doesn't misinform folks of what my goal is. This PR brings the functionality that I laid out in that issue (including feedback from the comments), a future PR will concentrate on making it look awesome.

On Sunday, May 5, 2013 at 15:59, Brent Beer wrote:

I'm late to the game on replying to this, please accept my apologies! I really like the idea of one single place for an app (as mentioned in other issues and in conversations in person). Do we see this competing or helping with zen.coderdojo.com or this is just an alternative if you want to use more of a GitHub workflow to your lesson (storing your lessons on GitHub, managing mentors this way, etc)

— Reply to this email directly or view it on GitHub (https://github.com/CoderDojoSF/event-app/issues/9#issuecomment-17461005).

[cameronmcefee]

I talked to James a bit about the lesson.json concept and he really liked the idea. Here's kind of how I see that working and how we might grow it out into managing dojos:

Our local dojo app sources our org, looks for repos with lesson.json files and uses those to populate the app accordingly. On the macro level, the CoderDojo Organization app Kata does the same thing, but for every dojo out there and uses the lesson.json file to categorize and organize the lessons automatically so we don't need humans to curate all of the dojo content. If it's on GitHub under a dojo org with a lesson.json file, it's in kata, searchable, etc.

For dojos, perhaps we do the same distributed approach. Each dojo has a repo with their dojo info in it. It's then up to them whether they run their dojo with our app or their own. Their dojo app can hit their repo for a dojo.json file to run their own app. Then zen.coderdojo.com sources all known dojo orgs, looks for the dojo.json file in a dojo repo and generates the profiles automatically.

Doing it this way means we can build our app on rails and have it grab our data from the dojo.json file via the api, while other dojos could do theirs with php or python. We don't need to force everyone to use the same app. We just ask everyone to use some standardized information.

[brntbeer]

I like this standardize approach.

Just to ensure i'm following, are you saying each dojo would have a repo that has a dojo.json file so that their zen.coderdojo.com is filled out correctly but their lessons would still have a lesson.json to have their lessons filled out correctly?

[cameronmcefee]

Basically yes. The way I picture it, we're actually duplicating info for the greater good. Each dojo has their own site that is basically zen.coderdojo.com with one account (the app we're building here). There is then also the main zen.coderdojo.com app that acts as the central place that all the dojo profiles live. Both apps grab info from the same file in the same repo. It's more just a matter of how the information is handled by the app.

Same goes for the lesson.json files. The local app uses those files in each lesson repo to handle showing and collecting the lessons in non-github-savvy way for kids and parents of a single dojo. The main kata app uses that file to index and categorize all of the lessons present within the whole CoderDojo global organization.

[jonmagic]

The GitHub API limits the number of API requests you can make per hour without authenticating against the API. Due to the way I get the lesson.json files you can basically only do the whole process once an hour. The process looks like this:

1. 1 API request to get a list of public repositories in the organization.
2. An API request to each of those repositories to try and grab a lesson.json file.

Right now that is ~21 API requests and as our number of repositories grows that number keeps growing. This means we're going to have to authenticate against the API in order to make all of the requests we need as the number of lessons grows.

I mention all of this because the zen app would have to do the same thing, so I just want folks to be aware of the limitations, or better put, the requirement to use an authentication token when hitting the API in order to not get shut off by rate limiting.

I'll be playing with all of this more over the next couple of weeks and I'll start writing up some documentation on the best way to approach the problem. I'll try and do the docs in language agnostic way so that it is applicable to other dojos that might not want to use ruby.

On Monday, May 6, 2013 at 9:05 AM, Cameron McEfee wrote:

Basically yes. The way I picture it, we're actually duplicating info for the greater good. Each dojo has their own site that is basically zen.coderdojo.com (http://zen.coderdojo.com) with one account (the app we're building here). There is then also the main zen.coderdojo.com (http://zen.coderdojo.com) app that acts as the central place that all the dojo profiles live. Both apps grab info from the same file in the same repo. It's more just a matter of how the information is handled by the app. Same goes for the lesson.json files. The local app uses those files in each lesson repo to handle showing and collecting the lessons in non-github-savvy way for kids and parents of a single dojo. The main kata app uses that file to index and categorize all of the lessons present within the whole CoderDojo global organization.

— Reply to this email directly or view it on GitHub (https://github.com/CoderDojoSF/event-app/issues/9#issuecomment-17490876).

[cameronmcefee]

Ah good to know. Is what I suggest plausible? I'm mostly just doing high level brainstorming without worrying too much about what is or isn't technically possible.

you can basically only do the whole process once an hour

Since our sessions will happen at most once a week, hourly is pretty generous. An hour is fine with me.

[jonmagic]

I wish there were org level webhooks to send a message whenever a repo is created/updated, so that we could just scan it for a lesson.json on that event :)

On Monday, May 6, 2013 at 9:41 AM, Cameron McEfee wrote:

Ah good to know. Is what I suggest plausible? I'm mostly just doing high level brainstorming without worrying too much about what is or isn't technically possible.

you can basically only do the whole process once an hour

Since our sessions will happen at most once a week, hourly is pretty generous. An hour is fine with me.

— Reply to this email directly or view it on GitHub (https://github.com/CoderDojoSF/event-app/issues/9#issuecomment-17492824).

[cameronmcefee]

I think we have some contacts at GitHub. Maybe we can bug one of them to add that.

[jonmagic]

First version is shipped and tested on production. You can try signing up for the test upcoming event on http://coderdojosf.herokuapp.com