Writing Clear and Maintainable README Files for Open Source
Designed for Contributors to early-stage open source projects who are software engineers with strong coding skills but little experience in writing public-facing documentation. to spark real collaboration and high-energy learning.
A 90-minute interactive virtual workshop for engineers maintaining new open source repositories. Participants are confident coders but often feel documentation is an afterthought, leading to onboarding headaches and missed contributions. The session is practical, hands-on, and aims to overcome the stigma that README writing is tedious or secondary to 'real' code work.
README Time Machine
Start with a brief, fascinating before-and-after showcase of a well-known open source project’s README (e.g., Kubernetes) from its earliest days to today. Participants compare screenshots and jot down quick impressions of how the README’s clarity may have helped (or hindered) the project’s growth.
Tap to view the full activity.
Why this works
Comparison sparks curiosity and quickly demonstrates the real impact of README evolution, building buy-in for why this matters.
README MythBusters
Bust common myths through a quick poll and group discussion: ‘A README is just a project description,’ ‘Only code matters,’ or ‘It’s fine to copy-paste from another repo.’ After voting, review stats showing how clear READMEs impact user adoption and contributor rates.
Tap to view the full activity.
Why this works
Dispelling misconceptions up front removes blockers to engagement and primes participants to unlearn old habits.
README One-Line Rewrite
Each participant receives a real (but anonymized) first line from a lackluster README. Ask them to rewrite it in one minute to be more inviting or informative. Share a few rewrites to highlight quick wins without pressure.
Tap to view the full activity.
Why this works
Low-stakes, immediate practice builds confidence and shows that everyone can improve documentation with small tweaks.
README Relay Race
Split the group into small teams. Each team gets the same messy README excerpt and 5 minutes to ‘clean it up’ using best practices discussed (clear sections, contributor info, friendly tone). After, teams read their improved versions in a rapid-fire relay.
Tap to view the full activity.
Why this works
Short, timed teamwork energizes the room and shows off just how quickly a README can be improved when everyone lends a hand.
The Broken Onboarding Dilemma
Share a brief, real-world scenario: A potential contributor tried using a project but abandoned it due to an unclear README. As a group, brainstorm exactly what information or structure could have turned this around—and what was missing.
Tap to view the full activity.
Why this works
Concrete dilemmas create a sense of urgency and purpose, allowing participants to empathize and problem-solve with a real context.
README Resolution Roadmap
Guide each participant to reflect on their own project’s README: What’s one promise they’ll make to improve it this month? They jot this down privately, then (optionally) share in chat or with a partner. End with a nudge to put 15 minutes on their calendar today.
Tap to view the full activity.
Why this works
Personal commitments and simple action steps anchor learning, moving it from insight to real-world follow-through.
Sign up to unlock 3 more activities
Get the full pack, facilitation flow, and more ready-to-run ideas.