|
| 1 | +# Contributing to Lessons for Librarians in Open Science |
| 2 | + |
| 3 | +Thank you for your interest in contributing to the Lessons for Librarians in Open Science project! This project is built by and for the library community, and we welcome contributions of all kinds - especially from those who teach, pilot, and engage with our lessons. |
| 4 | + |
| 5 | +By contributing to this project, you are agreeing that The Carpentries and UCLA may redistribute your work under [our license](LICENSE.txt). You also agree to abide by our [contributor code of conduct](#code-of-conduct). |
| 6 | + |
| 7 | +## Who We're Looking For |
| 8 | + |
| 9 | +We especially value contributions from: |
| 10 | + |
| 11 | +- **Librarians and information professionals** who work with researchers and students |
| 12 | +- **Instructors** who have experience teaching technical workshops or information literacy |
| 13 | +- **Open science practitioners** who can provide real-world context and examples |
| 14 | +- **Learners** who have taken or are taking these lessons and can offer fresh perspectives |
| 15 | +- **Developers and designers** who can help improve the technical infrastructure |
| 16 | + |
| 17 | +You don't need to be a Git expert or a programmer to contribute. We welcome contributions at all technical levels! |
| 18 | + |
| 19 | +## Ways to Contribute |
| 20 | + |
| 21 | +### 🎯 Priority: Pilot Our Lessons! |
| 22 | + |
| 23 | +**The most valuable contribution you can make is to teach one of our lessons.** We are actively seeking instructors to pilot our curriculum. When you pilot a lesson, you: |
| 24 | + |
| 25 | +- Gain hands-on experience with open science tools and methods |
| 26 | +- Help us identify areas that need clarification or improvement |
| 27 | +- Provide authentic feedback about pacing, difficulty, and learner comprehension |
| 28 | +- Contribute to the evidence base for lesson effectiveness |
| 29 | + |
| 30 | +**How to get started with piloting:** |
| 31 | + |
| 32 | +1. **Express Interest**: [Fill out our Pilot Interest form](https://github.com/ucla-imls-open-sci/ucla-imls-open-sci.github.io/issues/new?template=pilot-interest.yml) or open a GitHub issue with the "pilot" label |
| 33 | +2. **Choose a Lesson**: Browse our [lesson catalog](https://ucla-imls-open-sci.info) and select one that fits your audience and expertise |
| 34 | +3. **Prepare**: Review the lesson materials, instructor notes, and setup instructions |
| 35 | +4. **Teach**: Deliver the lesson to your learners (in-person, hybrid, or virtual) |
| 36 | +5. **Report Back**: Share your experience using our [Pilot Report template](#pilot-report-template) (see below) |
| 37 | + |
| 38 | +We provide support for pilots including: |
| 39 | +- Access to lesson authors for questions |
| 40 | +- Community of practice discussions with other pilots |
| 41 | +- Recognition and co-authorship credit for substantial contributions |
| 42 | + |
| 43 | +### 💬 Share Your Teaching Experience |
| 44 | + |
| 45 | +Have you already taught one of our lessons or a related topic? We'd love to hear about it! |
| 46 | + |
| 47 | +- **File an issue** describing what worked well and what could be improved |
| 48 | +- **Share your adaptations** - Did you modify the lesson for your context? Tell us how! |
| 49 | +- **Report timing issues** - Did certain sections take longer or shorter than expected? |
| 50 | +- **Identify confusing sections** - Where did learners get stuck or ask for clarification? |
| 51 | + |
| 52 | +### 🐛 Report Issues and Bugs |
| 53 | + |
| 54 | +If you find errors, broken links, outdated information, or technical problems: |
| 55 | + |
| 56 | +1. **Check existing issues** to see if it's already been reported |
| 57 | +2. **Open a new issue** with a clear title and description |
| 58 | +3. **Include details**: Which lesson? What page or section? What did you expect vs. what happened? |
| 59 | +4. **Screenshots help!** If it's a visual issue, include a screenshot |
| 60 | + |
| 61 | +You can report issues even if you don't know how to fix them. Fresh eyes often catch things that maintainers miss! |
| 62 | + |
| 63 | +### ✏️ Suggest Improvements |
| 64 | + |
| 65 | +We welcome suggestions for: |
| 66 | + |
| 67 | +- **Content clarifications** - Better explanations, additional examples, or helpful diagrams |
| 68 | +- **Accessibility improvements** - Making lessons more accessible to diverse learners |
| 69 | +- **Updated resources** - New tools, updated links, or current examples |
| 70 | +- **Cultural context** - Examples that resonate with diverse geographic and institutional contexts |
| 71 | +- **Additional exercises** - Practice opportunities that reinforce learning objectives |
| 72 | + |
| 73 | +You can suggest improvements by: |
| 74 | +- Opening a GitHub issue with the "enhancement" label |
| 75 | +- Emailing the project team (see [README.md](README.md) for contact info) |
| 76 | +- Participating in community discussions |
| 77 | + |
| 78 | +### 🔧 Submit Pull Requests |
| 79 | + |
| 80 | +If you're comfortable with Git and GitHub, you can contribute directly: |
| 81 | + |
| 82 | +1. **Fork** this repository to your GitHub account |
| 83 | +2. **Clone** your fork to your local machine |
| 84 | +3. **Create a branch** for your changes: `git checkout -b descriptive-branch-name` |
| 85 | +4. **Make your changes** following our [style guide](#style-guide) |
| 86 | +5. **Test locally** using `npm run dev` to preview your changes |
| 87 | +6. **Commit** with clear, descriptive messages |
| 88 | +7. **Push** to your fork: `git push origin descriptive-branch-name` |
| 89 | +8. **Open a Pull Request** from your fork to our `main` branch |
| 90 | + |
| 91 | +In your pull request description, please: |
| 92 | +- Explain what you changed and why |
| 93 | +- Reference any related issues (e.g., "Fixes #123") |
| 94 | +- Describe how you tested your changes |
| 95 | + |
| 96 | +### 🌍 Translate Lessons |
| 97 | + |
| 98 | +We welcome efforts to make these materials accessible in languages other than English. If you're interested in translating a lesson: |
| 99 | + |
| 100 | +1. Open an issue to let us know which lesson and language |
| 101 | +2. We'll help coordinate to avoid duplication of effort |
| 102 | +3. Follow translation best practices (we can provide guidance) |
| 103 | +4. Consider cultural adaptation, not just literal translation |
| 104 | + |
| 105 | +### 📚 Share How You're Using Our Materials |
| 106 | + |
| 107 | +We'd love to know how our lessons are being used! Share with us: |
| 108 | + |
| 109 | +- Blog posts about your teaching experience |
| 110 | +- Adaptations for specific audiences or contexts |
| 111 | +- Integration with other curricula or programs |
| 112 | +- Success stories from learners |
| 113 | + |
| 114 | +Tag us or open an issue to share your story! |
| 115 | + |
| 116 | +## What We're Not Looking For |
| 117 | + |
| 118 | +To keep our lessons focused and maintainable, we generally don't accept: |
| 119 | + |
| 120 | +- **Substantial new content** that extends beyond current learning objectives (though we're open to new lesson proposals!) |
| 121 | +- **Tools or platforms** that only work on one operating system (we support Windows, macOS, and Linux) |
| 122 | +- **Commercial or proprietary tools** without open-source alternatives |
| 123 | +- **Significant scope changes** without prior discussion with maintainers |
| 124 | + |
| 125 | +If you're unsure whether your contribution fits, please open an issue to discuss it before investing significant time! |
| 126 | + |
| 127 | +## Pilot Report Template |
| 128 | + |
| 129 | +After piloting a lesson, please share your experience using this template. You can submit it as a GitHub issue with the "pilot-report" label, or email it to the project team. |
| 130 | + |
| 131 | +```markdown |
| 132 | +# Pilot Report: [Lesson Title] |
| 133 | + |
| 134 | +**Instructor(s)**: [Your name(s)] |
| 135 | +**Date(s)**: [When you taught it] |
| 136 | +**Format**: [In-person / Virtual / Hybrid] |
| 137 | +**Audience**: [Who were the learners? E.g., academic librarians, public librarians, library school students] |
| 138 | +**Number of learners**: [Approximate number] |
| 139 | +**Duration**: [How long did it take?] |
| 140 | + |
| 141 | +## What Worked Well |
| 142 | +[What aspects of the lesson were effective? What did learners respond well to?] |
| 143 | + |
| 144 | +## What Was Challenging |
| 145 | +[What parts were confusing, too difficult, or took longer than expected?] |
| 146 | + |
| 147 | +## Suggested Improvements |
| 148 | +[Specific suggestions for improving the lesson] |
| 149 | + |
| 150 | +## Timing Notes |
| 151 | +[How did actual timing compare to the lesson plan? Which sections took longer/shorter?] |
| 152 | + |
| 153 | +## Learner Feedback |
| 154 | +[What did learners say? Any notable quotes or observations?] |
| 155 | + |
| 156 | +## Context and Adaptations |
| 157 | +[Did you adapt the lesson for your context? How?] |
| 158 | + |
| 159 | +## Additional Resources Used |
| 160 | +[Did you supplement with any additional materials?] |
| 161 | + |
| 162 | +## Would you teach this lesson again? |
| 163 | +[Yes/No and why] |
| 164 | + |
| 165 | +## Overall Rating |
| 166 | +[On a scale of 1-5, how ready do you think this lesson is for wider adoption?] |
| 167 | + |
| 168 | +## Other Comments |
| 169 | +[Anything else we should know?] |
| 170 | +``` |
| 171 | + |
| 172 | +## Style Guide |
| 173 | + |
| 174 | +When contributing content to lessons or the website: |
| 175 | + |
| 176 | +### Writing Style |
| 177 | + |
| 178 | +- **Use inclusive language** - Avoid gendered pronouns; use "they/them" or rephrase |
| 179 | +- **Write for an international audience** - Avoid region-specific idioms or cultural references |
| 180 | +- **Use active voice** - "Run the command" not "The command should be run" |
| 181 | +- **Define technical terms** - The first time you use a technical term, define it |
| 182 | +- **Provide examples** - Concrete examples help clarify abstract concepts |
| 183 | +- **Keep it concise** - Librarians are busy; respect their time |
| 184 | + |
| 185 | +### Formatting |
| 186 | + |
| 187 | +- Use **Markdown** for all lesson content |
| 188 | +- Follow the **Carpentries lesson template** conventions |
| 189 | +- Use **clear, descriptive headings** for navigation |
| 190 | +- Include **alt text** for all images |
| 191 | +- Test all **hyperlinks** to ensure they work |
| 192 | +- Use **code blocks** with syntax highlighting for code examples |
| 193 | + |
| 194 | +### Accessibility |
| 195 | + |
| 196 | +- Provide **text alternatives** for visual content |
| 197 | +- Use **sufficient color contrast** in diagrams |
| 198 | +- Write **clear link text** (not "click here") |
| 199 | +- Structure content with **proper heading hierarchy** |
| 200 | +- Ensure materials work with **screen readers** |
| 201 | + |
| 202 | +## Code of Conduct |
| 203 | + |
| 204 | +All contributors are expected to follow The Carpentries Code of Conduct. We are dedicated to providing a welcoming and supportive environment for all people, regardless of background or identity. |
| 205 | + |
| 206 | +**In brief:** |
| 207 | +- Use welcoming and inclusive language |
| 208 | +- Be respectful of differing viewpoints and experiences |
| 209 | +- Gracefully accept constructive criticism |
| 210 | +- Focus on what is best for the community |
| 211 | +- Show empathy towards other community members |
| 212 | + |
| 213 | +Unacceptable behavior includes: |
| 214 | +- Harassment, intimidation, or discrimination in any form |
| 215 | +- Unwelcome sexual attention or advances |
| 216 | +- Trolling, insulting/derogatory comments, and personal or political attacks |
| 217 | +- Publishing others' private information without explicit permission |
| 218 | + |
| 219 | +If you experience or witness unacceptable behavior, please report it to the project team at [[email protected]](mailto:[email protected]). |
| 220 | + |
| 221 | +## Getting Help |
| 222 | + |
| 223 | +Not sure how to get started? Have questions about contributing? |
| 224 | + |
| 225 | +- **Open an issue** with your question |
| 226 | +- **Email the project team **: [email protected] |
| 227 | +- **Check our documentation**: [GUIDE.md](GUIDE.md) for technical details |
| 228 | +- **Join the conversation**: Look for community discussion opportunities on our website |
| 229 | + |
| 230 | +We're here to help and want to make contributing as smooth as possible! |
| 231 | + |
| 232 | +## Recognition |
| 233 | + |
| 234 | +We recognize all contributors to this project. Contributions are acknowledged in several ways: |
| 235 | + |
| 236 | +- **Pilot instructors** are credited in lesson metadata and acknowledged on the website |
| 237 | +- **Substantial content contributors** may be listed as co-authors |
| 238 | +- **All contributors** are listed in the repository's commit history |
| 239 | +- **Issue reporters and discussants** help shape the lessons and are valued members of the community |
| 240 | + |
| 241 | +Thank you for helping make open science education more accessible to librarians worldwide! |
| 242 | + |
| 243 | +--- |
| 244 | + |
| 245 | +## Questions? |
| 246 | + |
| 247 | +If you have questions about contributing that aren't answered here, please: |
| 248 | +- Open an issue with the "question" label |
| 249 | + |
| 250 | +- Check our [README.md](README.md) for more project information |
| 251 | + |
| 252 | +**We look forward to your contributions!** |
0 commit comments