I'd like to review your README
1–10 of 94 posts
Re: I'd like to review your README
#2Great initiative! Thank you for doing this, it's definitely nice from your side to spend time on community, especially if you have strong opinions on README look.
I wonder only, how to scale it (: Is there a way for anyone to help with this effort, while not spending O(n) time. Automation?
Re: I'd like to review your README
#3Many READMEs would be greatly improved with a one paragraph introduction to the topic, defining all the terms used and outlining the problem that the project is trying to solve.
Re: I'd like to review your README
#4Great initiative! Thank you for doing this, it's definitely nice from your side to spend time on community, especially if you have strong opinions on README look. I wonder only, how to scale it (: Is there a way for anyone to help with this effort, while not spending O(n) time. Automation?
A template of a README with an example of outstanding README may help on wider scale.
Re: I'd like to review your README
#5Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place.
Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.
Re: I'd like to review your README
#6I won't even consider projects who's READMEs don't include enough info on what it is and basic steps for bootstrapping it up.
Re: I'd like to review your README
#7This is a great idea, and worth encouraging.
Some tips to be aware of in order to maintain a healthy contributor/maintainer ecosystem:
Bear in mind the volume of requests that the project/maintainers may have to deal with. This is usually fairly open and transparent with most FLOSS projects.
It's always good to test and understand your changes before submitting them - and if you can demonstrate that to the maintainers (by way of test coverage, screenshots, console output, etc), that'll increase the likelihood that your changes can be accepted, and can increase your reputation for respecting maintainer time.
If you feel like you _didn't_ fully test/understand your changes and they _were_ accepted regardless, that could be a sign that the project needs a bit more help with review and quality control. That can be a challenge, and it can also be an opportunity to provide other improvements (for example, by code reviewing and/or increasing test and continuous integration coverage).
PS: It might sound like a lot of this refers purely to code changes - but READMEs and documentation can be equally important to keep correct.
Re: I'd like to review your README
#8It's a really nice offer.
I found one small typo: "Part of the~~w~~ review process"
I'm sorry, it's kind of a trigger for me to read READMEs with typos and I need to send a PR to fix it.
Re: I'd like to review your README
#9Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place. Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.
I'm so lost when looking at READMEs or web pages like that. It will tell me that it's going to solve my problem faster and better than all other solutions out there. But I still don't know what my problem is.
Always start with the problem. Tools don't exist just for fun, they exist because we need them.
Re: I'd like to review your README
#10Pet peeve of mine: READMEs starting to explain hoe efficient, performant or minimal something is without explaining wat it is and why it should exist in the first place. Or using overly vague terms that only make sense in a very narrow technical context. A ‘minimal isomorphic asynchronous worker framework’. Can mean a million things.
In some cases it is valid for a project to write for a particularly niche audience; it may be difficult to write for everyone. But yep, sometimes they may simply need help improving their messaging.