Feedmereadmes: A README help exchange
This project originated at FOSDEM 2017 out of a conversation between folks at RedHat and Zalando. The idea is simple:
- If you're a project author who's looking for README feedback and help, add the link to your project README via the "Issues" feature on this repository. You can also tweet us your README link at @feedmereadmes. You'll receive:
- A pretty thorough README edit
- Project analysis/feedback to help you sharpen the "why," "how," and "what" behind your work. We use Zalando's product analysis template and other resources for this part. :)
- If you're a writer or editor who's interested in helping the open source community but not sure where to start, you can start right here. :) Go to the Issues, find a README to edit, and start working your wordsmith magic.
- If you're a product specialist/owner/manager who wants to contribute to open source development, you can lend your expertise to help project creators strengthen their project purpose and vision (which will make for better READMEs).
Press/More Info
Why We're Doing This
In 2010, GitHub founder Tom Preston-Warner wrote "README Driven Development," in which he advocated writing your README 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 for many. How this plays out:
- READMEs come without basic install/run/config instructions, creating needless friction for potential users and contributors.
- READMEs don't explain the "Why" and "How" behind the project—why it exists, how it's unique, how it solves problems.
- too-short or outdated READMEs.
Taking a README-driven development approach can resolve some of these issues immediately. But even if you don't support Preston-Warner's argument, you can still make sure your README user-friendly. We advise defining "user" broadly, to include your colleagues, your language community, your manager, your idols, journalists, fellow FOSS addicts who are in a hurry, your parents. Tell a story that others can comprehend.
Make "code isn't self-documenting" one of your mantras, as per Mike Jang's 2015 OSCON talk offering Ten Steps to Better READMEs.
We're here to help you, by connecting you to an audience of OSS enthusiasts and writing/editing professionals willing to offer you feedback and direction.
Our Project Aims, in No Specific Order:
- make READMEs clearer and more useful
- help project creators place their work in a bigger context: why their work exists, what it does, what it doesn't do, etc.
- offer guidance that might not be readily available to individual creators
- generate discussions around style, which could ideally lead docs teams to create style guides detailing preferences (for examples, Chicago vs. AP style, etc.)
- draw more attention to docs and doc-writing among developers
- increase non-dev involvement in OSS by providing a safe, simple, fun gateway (or gateway drug?!) for contributing
A Note to FOSS First-Timers Who Write/Edit: Why Work for Free?
Some of us recently worked as full-time writers and editors, and understand that being asked to do work for free can be annoying and even insulting. Free doesn't buy dinner, or pay the rent.
With that in mind, think carefully about why you want to contribute to a project. It might be to increase your knowledge of technology and open source; collaborate with creative people; help a struggling developer; or build your portfolio with different job prospects in mind. Maybe you're attracted to FOSS's spirit of free exchange and information sharing.
Don't overcommit. Start small and help 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. Software development is a dynamic industry, in which it's possible to make your own job—especially if your communication skills are strong. There are no guarantees, but helping some projects to improve their docs is a low-friction way to share your value with others who might want to compensate you.
One thing to keep in mind, in FOSS and in life: Go where it's warm. If project creators are taking advantage of you or making you feel uncomfortable, find another project. Seek collaborators who make you feel respected, appreciated, and "one of them." Don't settle for less.
For GitHub First-Timers
If this is your first time using GitHub, this tutorial can help you get started. You can also leave a comment in the Issues Tracker; just add "HELP: [your questions/needs]" in your issue.