Contributing to the curriculum

Our curriculum is open source, and we invite contributions from our learners, alumni community, and even external contributors. We would like potential contributors to follow our process, as laid out in this document.

Opening issues

GitHub issues are central to our process. No work should be done on the curriculum without first being captured and discussed in an issue. This ensures the team are on the same page, have a chance to discuss suggestions, and can assign work to the appropriate people.

Please do not start working on the curriculum without engaging with the team first. This means opening an issue if you can't see one already present, or commenting on the existing discussion to express interest in the work. Opening a pull request without engaging could lead to you wasting your time if the work is not relevant, or duplicated, or otherwise does not fit the teams's goals.

Pull requests

Once you have established that a contribution would be welcomed please open a pull request with your changes. This will allow the maintainers to review your work and provide any feedback.

Try to follow good Git practices—divide your work into granular commits with descriptive messages. Use the pull request description to describe the high-level changes (screenshots are often helpful), and why the changes are needed.

The maintainers may provide suggested changes in their feedback—please don't take these as personal criticisms. It is important to us that new curriculum material meets a high standard, and is consistent with the existing material.

Workshop contributions

If you are writing an entirely new workshop it is important the material follows the same structure as our existing workshops. Read through some of the current curriculum to get a sense for how these are written, and try to match it.

Balance

Workshops should have a balance between explaining new concepts and allowing learners to practice and figure things out on their own. If a concept is new to the learners, and is very important to understand correctly, then explain it clearly and in detail. For more minor concepts it is a good idea to lead learners to the right conclusions through examples or challenges.

Examples

Try to keep code examples minimal and focused. Don't include extraneous surrounding code unless it is absolutely necessary for understanding. Make sure the code is clear, with descriptively named variables. Try to do things in the most "normal" way—avoid overly clever solutions that force learners to stop and think about them. Remember that learners are likely to use example code as the basis for their projects, so make sure it is robust. If there are edge-cases or important things left out for brevity make sure to highlight this.

Challenges

Try to keep learners engaged by using interactive "mini-challenges" throughout the learning material. Sometimes it is unavoidable that learners have to read through a longer technical section to absord a new concept. Try to break this up by having them try out new things, even if just in the console of their browser. These challenges should not require lots of deep thinking or time investment—they are just to help concepts sink in and maintain learner engagement.

These mini-challenges should have an expandable solutions section inline so learners can quickly verify their work without spending too long on each section.

Learnings should be reinforced by more in-depth challenges at the end of major sections. This is where the real learning happens—these should reinforce the information just presented and require the learners to reflect back on the information and apply it in a potentially novel way. Ideally the challenge should require a certain amount of repetition to ensure the knowledge sticks.