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.

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.

This is my main issue with Rspec documentation.

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.

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.

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.

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.

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.

That's a really good point.

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

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.

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.

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.

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.

Claiming "fast" implies that performance is a project goal, possibly even tracked over time as a metric, and that there's probably a comparison deeper in the README or elsewhere. It probably also means that when it comes to tradeoffs (compile time, code size, binary size, ergonomics, maybe even strictness/correctness), runtime speed is the preferred option.

"[description], aimed at speed" or something like that is better in that case, IMHO.

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

I think production ready on its own has value because it sets the stage of what to expect.

There's a very big difference between a project being production ready or not. Production ready (to me at least) means the project has been thoroughly tested on a live site and is in a position where you can take it as is and run it in production with confidence that it's going to work.

For example I have a Docker + Flask example starter kit project at https://github.com/nickjj/docker-flask-example and the GitHub description is "A production ready example Flask app that's using Docker and Docker Compose.". In this context to me that says it's using multi-stage builds, env variables, deals with static files in a way that's cacheable (md5 hashes, etc.), has tests and overall you can expect to see patterns that work well in both dev and prod. The README goes over those details too in case you didn't infer that from only "production ready" too.

Plot twist: It took me longer to write the README than create the whole project.

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.

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.

> These type of words signal the author's intent

How many people intend to make slow, outdated, insecure software?

> when 1 (…) substantiated with concrete data

Then show me the data and let me reach my own conclusions. As a bonus point, the unquantifiable adjectives will be removed.

> Unfortunately, they are more often misused or abused than applied correctly.

Which makes them useless all of the time, because by now we’re primed to ignore those claims.

> How many people intend to make slow, outdated, insecure software? The point is that some authors may claim simplicity, some may claim performance, others more security and so on. It is rare to have all adjectives thrown in - and easy to discard when you see them.

>because by now we’re primed to ignore those claims. Unfortunately, we don't always. If we were ignoring them all, then we wouldn't care. It is that we can't help read and interpret them and have our expectations set up; hence the disappointment when it turned out to be just words.

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.

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

Nodejs