Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

I'd like to review your README

liw.fi

Post reply on HN
Print view View original

31–40 of 94 posts

Re: I'd like to review your README

#31

Post by ttty »

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. I'm willing to spend an hour per project, in total. I choose which projects to work on and how many projects.

A README should have an example of how to typically use the software. It should say how the copyright and other legal aspects affect the project. A README can also contain instructions for installing the software, or how to run its test suite.

Re: I'd like to review your README

#32

Post by rendaw »

tirrex wrote: post #18
sfvisser wrote: post #5

Pet 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'd expect a fast json parser to be harder to use than an easy-to-use or simple one. But if I need to eke out maximum performance on something I'm going to skip the ones that don't have fast in the description - it means the project's goals aren't aligned with my use case. If it's a web project then I'm going to focus on parsers that have have actually considered security over the ones that haven't.

These are all important words for describing projects.

Re: I'd like to review your README

#34

Post by noxer »

I wish people would find a way to include any code present in a README in some kind of automated test.

Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated

Maybe not include any code is the better solution, instead add an example folder.

Re: I'd like to review your README

#36

Post by franciscop »

noxer wrote: post #34

I wish people would find a way to include any code present in a README in some kind of automated test. Nothing more frustrating than if you copy something from there but it turns out the README wasn't updated since the very first day and all the "hello world" code or install instructions are completely outdated Maybe not include any code is the better solution, instead add an example folder.

I did that! I hope you are not the person who suffered that from me (did you use Picnic CSS a few years back?). So for a newer project I put some setup code that will look for all code snippets with a specific comment and run that with the code after the comment. For generating the website documentation that test bit can be stripped (though I kept it for now).

Example: https://github.com/franciscop/server/blob/master/docs/docume...

Re: I'd like to review your README

#37

Post by s3ker »

rendaw wrote: post #32
tirrex wrote: post #18

Earlier quoted context omitted.

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'd expect a fast json parser to be harder to use than an easy-to-use or simple one. But if I need to eke out maximum performance on something I'm going to skip the ones that don't have fast in the description - it means the project's goals aren't aligned with my use case. If it's a web project then I'm going to focus on parsers that have have actually considered security over the ones that haven't. These are all imp…

You forgot to add military-grade encryption and cloud-native tags

Re: I'd like to review your README

#38

Post by johnchristopher »

rendaw wrote: post #32
tirrex wrote: post #18

Earlier quoted context omitted.

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'd expect a fast json parser to be harder to use than an easy-to-use or simple one. But if I need to eke out maximum performance on something I'm going to skip the ones that don't have fast in the description - it means the project's goals aren't aligned with my use case. If it's a web project then I'm going to focus on parsers that have have actually considered security over the ones that haven't. These are all imp…

Fast is not a KPI though. It can and is often labeled on anything, making the term useless even when fast is a criteria over ease of us.

Maybe something at the top along the lines of : what it does, how and then what are the implications.

Re: I'd like to review your README

#39

Post by colour »

sfvisser wrote: post #5

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

Code for asynchronous work, but it's isomorphic whatever that means.
Post reply on HN