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.
• 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.

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 that come without basic install/run/config instructions, creating needless friction for potential users and contributors.
• READMEs that don't explain the "Why" and "How" behind the project—why it exists, why it's different from similar projects, how it's used in production by the creators or others, and how it's architected.
• READMEs that are either too short or too cluttered.

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.

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
• 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 changes in the industry have made it harder to get paid for words. Some of us have done writing work for free, and it doesn't feel good. Free doesn't buy dinner, or pay the rent.

With that in mind, think carefully about why you want to contribute your writing and editing skills to making the world's READMEs more readable. It might be to increase your knowledge of technology and open source; collaborate with creative people; help a struggling developer improve their project in a way you find simple, but that they might find difficult; or build your portfolio with different job prospects in mind. Maybe you're attracted to FOSS's spirit of free exchange and information sharing. These are just some of the reasons why many of us all over the world spend our nights and weekends at our computers, doing work for no monetary compensation.

Maybe you'll quickly find that helping FOSS projects is something you love. Maybe you'll quickly question what you're doing. With that in mind, start small. Don't overcommit. 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.