Feedmereadmes: A README Help Exchange
This project originated during a conversation at FOSDEM 2017 between folks at RedHat and 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. You'll receive a thorough README edit and feedback to help you sharpen your project's "why," "how," and "what." We apply Zalando's product analysis template and other resources for this. :)
- 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 wordsmith 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 expertise to help devs strengthen their project purpose and vision.
Note: We only edit READMEs, not full sets of documentation or manuals. We reserve the right to reject not-READMEs as we are providing free help and have time constraints. Please send us only READMEs!
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
In "README Driven Development," GitHub founder Tom Preston-Warner advised devs to write their READMEs first. "First. As in, before you write any code or tests or behaviors or stories or ANYTHING," he wrote. "I know, I know, we’re programmers, dammit, not tech writers! But that’s where you’re wrong. Writing a Readme is absolutely essential to writing good software. Until you’ve written about your software, you have no idea what you’ll be coding."
Years later, 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.
Even if you don't agree with Preston-Warner, you can still make your READMEs user-friendlier. Feedmereadmes is here to help. 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.
