This session focuses on organizational and technical aspects of collaborative lesson development.
This session is about **collaborative** lesson development. What advantages do
you see in developing lessons collaboratively and sharing lessons (making
material accessible)? What difficulties are there?
- Jekyll-based
- Example: Introduction to version control with Git
- Lesson template
- Common styling implemented as Git submodule: jekyll-common
- Based on a past version of the Carpentries lesson style
- A new Carpentries lesson template is in the works
- Sphinx-based
- Example: this lesson
- Starting point: sphinx-lesson
- Documentation
- Templates can be freely re-used
Why static sites?
- Decentralized (in terms of organization/namespace)
- Forkable
- Anybody can suggest changes
Creating new teaching material is a longer process, because you should go through the whole backwards lesson design process and get extensive comments. Still, don't feel afraid: nothing is perfect (or even good) the first time. In fact, it may be an advantage to share an imperfect lesson with others early to collect feedback and suggestions before the lesson "solidifies" too much. Draft it and collect feedback. The result will probably be better than working in isolation towards a "perfect" lesson.
How can we share unfinished work/ideas?
- Draft pull requests (GitHub) or WIP (work in progress) merge requests (GitLab).
- Open an issue and discuss your idea before implementing it.
Our lessons are collaboratively developed. They are made by many people, and there is no single fixed master plan (but there should be, in the instructors or maintainer's guide). We encourage everyone to contribute to the lessons.
Lessons are reviewed very often - essentially, before each workshop by the instructor of that workshop. This can be a quick review, looking at issues and fixing easy things, or more thorough.
Every so often (such as at this training), there is an extensive hackathon period of fully revising a lesson and making major improvements.
We've made the lesson-review checklist to guide the review process.
We now go to the
[lesson-review](https://coderefinery.github.io/manuals/lesson-review/)
checklist and discuss it, instead of duplicating things here.
- Convert feedback about lessons and suggestions for improvements into issues so that these don't get lost.
- Make your lesson citable: get a DOI.
- Credit contributors (not only Git commits).
- Instructor guide is essential for new instructors.
- Lesson changes should be accompanied with instructor guide changes (it's like a documentation for the lesson material).
- Apply and validate backwards lesson design again and again.
- Make it possible to try out new ideas (by making the lesson branch-able).
- Before making larger changes, talk with somebody and discuss these changes.
- For substantial changes we recommend to first open an issue and describe your idea and collect feedback before you start with an extensive rewrite.
- For things still under construction, open a draft pull request to collect feedback and to signal to others what you are working on.