27 ms·

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 fir

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.

globular-toast 6y ago
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.
jka 6y ago
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.
DandyDev 6y ago
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 6y 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 6y 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 6y 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 6y ago
    That's a really good point. I need to either find or write a good readme template with that in mind.
- daveFNbuck 6y 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.
tirrex 6y ago
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.
- lgreiv 6y ago
  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.
  - iudqnolq 6y ago
    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.
    - lgreiv 6y ago
      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.
- astatine 6y ago
  This sounds right, though it doesn't have to be. These type of words signal the author's intent and when 1 - justified by the actual deliverable 2 - substantiated with concrete data can be very useful. They can help create the right expectation. Unfortunately, they are more often misused or abused than applied correctly.
colour 6y ago
Code for asynchronous work, but it's isomorphic whatever that means.
- syspec 6y ago
  Nodejs
frou_dh 6y ago
Here's my README pet peeve: When the examples for some tool that operates on source code show it operating on its own code. As a reader unfamiliar with a project, it's unpleasant to have to contend with "meta" at a time when one doesn't even have a solid first-order understanding of the project.
- nooyurrsdey 6y ago
  prism.js the code syntax highlighter is notoriously bad at this. At first I felt bad for being confused by something so simple. But all their code examples for highlighting refer to their own code and you're right, at the exact moment you're trying to absorb new information it is infuriating to deal with the "meta" examples. I don't use them out of that alone.
  - slhck 6y ago
    This is my main issue with Rspec documentation.
    - pizzapill 6y ago
      RSpec has none of that, a typical example from the first page of their documentation: RSpec.describe Widget do example do expect(described_class).to equal(Widget) end end Pretty non-meta.

globular-toast 6y ago

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.

jka 6y ago

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.

DandyDev 6y ago

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 6y 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 6y 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 6y 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 6y ago
  That's a really good point. I need to either find or write a good readme template with that in mind.
daveFNbuck 6y 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.

tirrex 6y ago

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.

lgreiv 6y ago
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.
- iudqnolq 6y ago
  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.
  - lgreiv 6y ago
    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.
astatine 6y ago
This sounds right, though it doesn't have to be. These type of words signal the author's intent and when 1 - justified by the actual deliverable 2 - substantiated with concrete data can be very useful. They can help create the right expectation. Unfortunately, they are more often misused or abused than applied correctly.

colour 6y ago

Code for asynchronous work, but it's isomorphic whatever that means.

syspec 6y ago
Nodejs

frou_dh 6y ago

Here's my README pet peeve: When the examples for some tool that operates on source code show it operating on its own code. As a reader unfamiliar with a project, it's unpleasant to have to contend with "meta" at a time when one doesn't even have a solid first-order understanding of the project.

nooyurrsdey 6y ago
prism.js the code syntax highlighter is notoriously bad at this. At first I felt bad for being confused by something so simple. But all their code examples for highlighting refer to their own code and you're right, at the exact moment you're trying to absorb new information it is infuriating to deal with the "meta" examples. I don't use them out of that alone.
- slhck 6y ago
  This is my main issue with Rspec documentation.
  - pizzapill 6y ago
    RSpec has none of that, a typical example from the first page of their documentation: RSpec.describe Widget do example do expect(described_class).to equal(Widget) end end Pretty non-meta.