2 ms·

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 cl

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.

Y-bar 5y ago
I'm not the person you responded to, but I think their peeve stands correct for technical README's as well. I've decided more than once to not continue reading those when is is not clear to me to move on to what might be a similar implementation just because the README never really explained if it was what I was looking for. The times when I need to read the repo README is when I am not familiar with what I am looking for. I say err on the side on more documentation, err on the side of a better explanation.
nooyurrsdey 5y ago
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.
- erikerikson 5y ago
  You have a point and I might reprioritize. Specialized terminology allows the communication of complex concepts compactly. For the specialists a brief description like you mentioned is perfect. If you give it first, that person can read it and decide. It should certainly be followed by a tear down or other plain English explanation of what the thing is. Kind of like: ``` Brief A little longer Be descriptive about the thing Go into every detail you want to discuss about the thing in the repository... ``` The jargon fooled blurb makes a great "a little longer" and gets out of the way to let the more readable description be given. Burying that can be a pain.
- bloopernova 5y ago
  That's a really good point. I need to either find or write a good readme template with that in mind.
daveFNbuck 5y ago
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.

Y-bar 5y ago

I'm not the person you responded to, but I think their peeve stands correct for technical README's as well. I've decided more than once to not continue reading those when is is not clear to me to move on to what might be a similar implementation just because the README never really explained if it was what I was looking for. The times when I need to read the repo README is when I am not familiar with what I am looking for. I say err on the side on more documentation, err on the side of a better explanation.

nooyurrsdey 5y ago

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.

erikerikson 5y ago
You have a point and I might reprioritize. Specialized terminology allows the communication of complex concepts compactly. For the specialists a brief description like you mentioned is perfect. If you give it first, that person can read it and decide. It should certainly be followed by a tear down or other plain English explanation of what the thing is. Kind of like: ``` Brief A little longer Be descriptive about the thing Go into every detail you want to discuss about the thing in the repository... ``` The jargon fooled blurb makes a great "a little longer" and gets out of the way to let the more readable description be given. Burying that can be a pain.
bloopernova 5y ago
That's a really good point. I need to either find or write a good readme template with that in mind.

daveFNbuck 5y ago

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.