Feedmereadmes: A README Help Exchange
This project originated during a conversation at FOSDEM 2017 between folks at RedHat and (at the time) Zalando. It's here to serve:
- project authors looking for README feedback and help. Add the link to your project README via this repository's Issues tracker to request editing support and feedback to help you sharpen your project's "why," "how," and "what." (If you want to try doing an edit yourself first, take a look at this product analysis templateโit offers guidance.)
- writers and editors who would like to help the open source community but aren't sure where to start. Pick a project in the Issues tracker and start working your magic. GitHub's tutorial for new users will help you to find your way.
- product specialists/managers who want to contribute to open source development. Lend your storytelling expertise to help project maintainers strengthen their project purpose and vision.
Note: Please submit only READMEs, not full sets of documentation or manuals.
Press + Quotes
- Red Hat/opensource.com
- "I love feadmereadmes" โ Brandon Keepers, GitHub
- "Great opportunity for #writers to contribute to FOSS!" โ Ivana Isadora Devcic, KDE Community
- "A truly excellent service to the community." โ Jerod Santo, The Changelog
Inspiration List
Go here for relevant articles, talks, and projects that we find inspiring. Add your own favorites via pull request.
Why We're Doing This
Documentation remains an overlooked part of OSS development. How this plays out:
- No basic install/run/config instructions, which creates friction for potential users.
- No explanation of why projects exist, how they're unique, or how they solve problems.
- too-short or outdated READMEs.
Feedmereadmes aims to help bridge the gap between project maintainers who want to make their docs user-friendly, and people with writing and editing skills who can help them. We define "user" to include non-developers and aim to tell compelling stories. "[C]ode isn't self-documenting" is one of our mantras, as per Mike Jang's 2015 OSCON talk offering Ten Steps to Better READMEs.
Our Project Aims, in No Specific Order:
- make READMEs clearer and more useful
- help project creators explain the "how" and "what"
- offer guidance that might otherwise be unavailable to individual creators
- generate discussions and new ideas around README development
- draw more attention to docs and doc-writing
- provide a safe, simple, fun gateway (or gateway drug?!) for non-devs to contribute to OSS
A Note to FOSS First-Timers Who Write/Edit: Why Work for Free?
Some of us have worked as full-time writers and editors. So we understand that requests to work for free can be annoying and even insulting. Free doesn't buy dinner, or pay the rent. With that in mind, consider why you want to contribute to a project. Don't over-commit. Start with helping one project, then assess your experience. Did you like it? Did you not? What would make it better? Would you do it again?
Many of us contribute to FOSS projects at work; we are lucky. You might not have this opportunity ... yet. Many of us non-devs working in the tech industry have created our own jobs. Our writing, editing and communications skills are valuable.
One thing to keep in mind, in FOSS and in life: Go where it's warm. If a project creator treats you poorly, assert your boundaries. Seek collaborators who make you feel respected, appreciated, and "one of us." Don't settle for less.