I'd like to review your README • Hacker News Board

Re: I'd like to review your README

#71

Post by M3t0r » Sat, Apr 17, 2021, 4:03 PM UTC

SuperCuber wrote: post #62

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 do something similar: my README contains the output of --help, and I have a CI step that ensures that all the lines of the actual help output are present in the README. Caught me a couple times forgetting to update new flags and version changes.

I've spent hours putting that functionality into a unit test. Worth every minute!

Re: I'd like to review your README

#72

Post by bloopernova » Sat, Apr 17, 2021, 4:06 PM UTC

nooyurrsdey wrote: post #49

DandyDev wrote: post #12

Earlier quoted context omitted.

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 fe…

Sure the individual words make sense but there's a cognitive load of deciphering that when you're first trying to learn something. A "plain english" no nonsense definition goes a long way to introduce your concept. Save the fancy technical jargon for further down in the README if you must.

That's a really good point.

I need to either find or write a good readme template with that in mind.

Re: I'd like to review your README

#73

Post by daptaq » Sat, Apr 17, 2021, 4:07 PM UTC

asutekku wrote: post #68

daptaq wrote: post #61

Earlier quoted context omitted.

The issue here is that it is meaningless when viewed locally. GitHub made the mistake of turning "README", a file you'd usually read when you download some code into a website format. A README is broken if lines aren't broken, it is full of badges or nonsense like a table of contents (as OP says, a README is not a manual).

To be fair, i haven’t read a local readme in years. Markdown in github is hands down miles better and provides more value than any local readme openable with any kind of computer could provide.

IMO a valid, human readable README file is will always also generate readable rendered output.

Re: I'd like to review your README

#74

Post by nandi95 » Sat, Apr 17, 2021, 4:34 PM UTC

I wish some people did that but for documentation

Re: I'd like to review your README

#75

Post by tele_ski » Sat, Apr 17, 2021, 4:42 PM UTC

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.

This is great advice and I wish it was the standard. I had this problem on one of my projects so I used a githook to basically paste in actual compiled example files from the test suite on committing. It does mean the actual readme is more like a template and you can't edit the README file directly anymore but all the examples always work now!

I personally like at least one small example embedded in the README since it's zero effort, an example folder is great for _more_, but annoying to get started, what should I look at in the example folder first?

Re: I'd like to review your README

#76

Post by daveFNbuck » Sat, Apr 17, 2021, 4:59 PM UTC

DandyDev wrote: post #12

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.

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 fe…

A lot of asynchronous job frameworks run workers on many machines across a cluster. That's a very different sort of framework than one that runs things in the background on a single machine, but the short description applies equally well to it.

Re: I'd like to review your README

#77

Post by pcthrowaway » Sat, Apr 17, 2021, 5:20 PM UTC

yboris wrote: post #56

If the repository is of an application, I strongly recommend people include a screenshot of it. It blows my mind when someone has spent hundreds of hours to make something that they'd like others to use, and didn't spend the 5 minutes needed to increase its use by (my estimate) at least 5%.

A good README is unlikely to be 5 minutes of time. I've spent ~5 hours on what I consider "OK" READMEs for our internal projects where I have a captive audience (so don't need to sell them on it)

Re: I'd like to review your README

#78

Post by einpoklum » Sat, Apr 17, 2021, 5:36 PM UTC

Won't this fellow's queue fill up for months once this link is posted here on HN?

Re: I'd like to review your README

#79

Post by syspec » Sat, Apr 17, 2021, 6:22 PM UTC

colour wrote: post #39

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.

Nodejs

Re: I'd like to review your README

#80

Post by lgreiv » Sat, Apr 17, 2021, 6:45 PM UTC

iudqnolq wrote: post #53

lgreiv wrote: post #20

Earlier quoted context omitted.

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.

I think "production ready" is essentially impossible without also being able to say "I/my employer/foocorp is running this in production" unless you're not allowed to say it for legal reasons. I think it would take a very experienced developer to predict in advance every issue they'd run into putting something into production.

The definition you gave is exactly how I would read `production-ready`. I might be overly optimistic in assuming that this is the case whenever someone uses the term, though.

> I think it would take a very experienced developer to predict in advance every issue they'd run into putting something into production.

I am not sure whether that can be expected from any project that exceeds a very narrow scope and/or if which it’s correctness can potentially be mathematically proven.