[tirrex]

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.

[rendaw]

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.

[johnchristopher]

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.

[mikepurvis]

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.

[jeddy3]

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

[s3ker]

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

[nickjj]

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.

[lgreiv]

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]

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]

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]

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.

[latexr]

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

[astatine]

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