It would be great if author points us a few READMEs he likes. So, people can avoid many issues before asking for review.
I'd like to review your README
11–20 of 94 posts
Re: I'd like to review your README
#12Pet 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.
To be fair, I think we're talking about READMEs for technical projects here, probably hosted on Github/Gitlab/... And in that context your example is totally clear to me: it's a framework for running (background) jobs asynchronously (i.e. code that does not need to run on the main thread of your program and block) and you can use it both on the server and the browser (so probably JS/TS) and it's not intended to be feature rich.
Re: I'd like to review your README
#13> A README is meant for someone who is first encountering the project to be able to quickly decide if they want to learn more about it.
In the past, by time I got to the readme I had already downloaded the project. It’s kind of weird how places like GitHub rendering the readme have changed the practice.
Re: I'd like to review your README
#14> I’d like to help others make better free and open source software so I’m making this standing offer: I’ll review your README for free.
On a more global discussion, I feel like a lot of experienced people are willing to help, or teach for free on subjects such as, startups, programming, product management, data science, tech subjects ... (and I assume on other non-tech topics also) but it is always hard to find people to help. I mean you could join a charity, but it is not the same thing as being close to one person and helping him in topics he is not good at.
Does anyone know a community where one can find people to help individually ?
Re: I'd like to review your README
#15Great initiative and very generous!
My pet peeve with READMEs: usage of excessive adjectives to oversell your project. Famous culprits: "blazingly fast" or software that is "beautiful" or creates "beautiful" things.
Re: I'd like to review your README
#16The rules for traditional README files are documented here:
https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...
https://www.gnu.org/prep/standards/standards.html#index-READ...
Re: I'd like to review your README
#17Great initiative and very generous! My pet peeve with READMEs: usage of excessive adjectives to oversell your project. Famous culprits: "blazingly fast" or software that is "beautiful" or creates "beautiful" things.
People are starting to adapt corporate PR and marketing jargon as sign of professionalism.
Another way to make yourself appear silly influencer is to use words like "I" and "My" in headlines ("I made a thing", "My thing hobby", "My thoughts on .."). Obviously it's you. But people don't know who you are and generally they don't care. Pushing persona makes everything look like social media marketing.
Re: I'd like to review your README
#18Pet 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.
fast, simple, scalable, modern, high performance, easy to use, enterprise-grade, secure, production-ready, new generation, lightweight ...
These are common words I see in the first paragraph of readmes. If people can avoid these, they’ll write better introductions. No marketing, no subjective words. Otherwise, I feel like someone is trying to sell me that product.
Re: I'd like to review your README
#19Great initiative and very generous! My pet peeve with READMEs: usage of excessive adjectives to oversell your project. Famous culprits: "blazingly fast" or software that is "beautiful" or creates "beautiful" things.
People are starting to adapt corporate PR and marketing jargon as sign of professionalism. Another way to make yourself appear silly influencer is to use words like "I" and "My" in headlines ("I made a thing", "My thing hobby", "My thoughts on .."). Obviously it's you. But people don't know who you are and generally they don't care. Pushing persona makes everything look like social media marketing.
And not only such. In the end this is how marketing works, there is always the feeling to be left: the feeling to be part of the in-group.
Re: I'd like to review your README
#20Pet 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.
fast, simple, scalable, modern, high performance, easy to use, enterprise-grade, secure, production-ready, new generation, lightweight ... These are common words I see in the first paragraph of readmes. If people can avoid these, they’ll write better introductions. No marketing, no subjective words. Otherwise, I feel like someone is trying to sell me that product.
I agree in general, except for `production-ready` which I deem useful information. Of course, it is only the maintainers‘ assessment on the state of the project and thus needs to be validated further by myself. But IMO that adjective signals that I can expect the author to be happy with the current API and behavior and can assume it will be relatively stable; probably battle-tested.