Writing for Reuse
A tremendous amount of work is going into developing lessons and demos for sharing coding skills with our colleagues worldwide; we can create a rich teaching resource if we combine these efforts by making all our lessons available & findable to each other. Here are some tips on writing for reuse:
- Keep it short. In order to be digestible and convenient, Study Group lessons are best suited to be about an hour. A good rule of thumb is to plan for 10 full minutes per major command or idea, after factoring in challenge problems, audience questions, and discussion of detials and, of course, setup time.
- Make sure it's complete. Does your lesson need or benefit from some example data? Does it require any dependencies to be installed beforehand? Make sure these are clearly included with the lesson.
- Keep the format simple. Plain text is best - it's easy to version control & distribute, easy for everyone to read and requires the least time for you to create. Markdown, particularly on GitHub, is a good option that is the next-simplest-thing to plain text.
- Make it easy to read. When someone uses your content, they are going to want to put their own spin on it; no need to record detailed explorations of the nuances of every idea. A bullet list of what commands to show in what order and where the challenge problems go, with short comments explaining the goal of each step, is both quickest for you to write and easiest for other people to digest.
Lesson Issue Index
Whenever someone at your group leads a lesson, open an issue here to let everyone know about it. Have a look at some of the other lesson issues for examples; each listing should have the following info:
- Link: a link to the lesson notes.
- Author: the author of the lesson, with a link to their github handle or twitter if possible.
- Video: a link to a webcast of the lesson, if available.
- Description: a one sentence description of the lesson.
Also, be sure to apply appropriate labels to the issue, so people can search by category for lessons that interest them. There are labels for topic, scientific field, and difficulty level; see below for the existing categories, and feel free to open an issue requesting a new category if none of the existing ones fit.
Lessons by Topic
- Articles considered in Journal Club
- Programming in R
- Programming in Python
- Programming in Perl
- Programming in the Bash Shell
- Version Control with Git
Lessons by Field
- Data Science
- Mapping & GIS
- Open Science
- Various Topics
Topics by Difficulty
Please contact the Mozilla Science Lab about your Study Group to ask questions, tell us how you're doing, or share what you've learned to improve this guide. You can email us, or open an issue or pull request about this guide, our template Mozilla Study Group website, or about our collection of lesson material. We look forward to working with you!