A standard format for lesson plans on GitHub

(John Britton) #1

Continuing the discussion from Open source lesson plans:

@robmuh I agree, it’d be great to have a sort of standard for lesson plans on GitHub. For now, I think we’re best served by creating and collecting as many lesson plans as possible to figure out what such a format would require. It’d be really cool to have a directory or registry of lesson plans on GitHub that is easily searchable. If such a directory existed, we could easily integrate it with Classroom to allow people to choose from existing lesson plans in sort of a “store”.

(Rob Muhlestein) #2

Here’s the one I started that also has a course.json, but I am completely redoing it as an assignment starter and with TOML instead of JSON (although the course.json will also be built by the docmaker (or whatever it ends up being named). I plan on reserving the www directory of the the course repos to contain a Phonegap-able miniapp containing the documentation built from a combination of README.md, with the structure in the TOML and then “styled” with some sort of probably React navigation button built into it. I had been playing around with a docmaker earlier but think I’m going to go with a golang version so the command line tool could be run on any supported OS without additional installations. This way students can use their tablets or phones to follow along, even mark off the GitHub Flavored Markdown check boxes for their own local reference as they work through the assignments in the course sort of like having a text book instead of having to go back and forth with windows to see the README.

I’ll make a working http://github.com/skilstak/boilerplate-course with the structure I’m standardizing on for SkilStak, and maybe it could at least evolve or factor into something of a bigger standard.

Speaking of standards, I would really appreciate any kind of influence anyone can bear over there at GitHub putting some wind in the sails of an official TOML Specification.. It is clearly the core of most of these hand-maintained data stores—especially the types that we are talking about. Imagine maintaining meta-data about our lessons, assignments, and courses using basic editors in TOML. (JSON has proven very unwieldy when doing this stuff by hand.)

I suggest a starting point on any kind of standard is a discussion of the domain language involved. A glossary of terms.

(Conrad Hollomon) #3

Why TOML, if you don’t mind me asking?

(Rob Muhlestein) #4

I find TOML to be a much easier format to maintain by hand, so do others. Several projects are beginning to adopt it instead of JSON (including the fastest Static Site Generator, Hugo)—especially where large text strings are involved. We could just as easily use JSON and in whatever packager we create have it optionally read TOML before generating the package. I think any kind of course packager configuration format needs to potentially accept very long strings of text easily.

(Philip Johnson) #5

I developed a GitHub based framework called “Morea” for structuring my classes and have been using it for several years along with several other instructors:


See the Gallery page for example sites:


It might be a useful reference point for your design efforts.


(Marino Linaje) #6

I have checked the examples and looks really nice. Very nice work!
I will check the code for the next semester classes. I was looking to do moodle lessons, mostly because it allows to include random questions from bank test inside the lessons,… another way should be to convert your courses to moodle lessons…
It’s something that requires further look at the code and formats for sure…