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.
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.
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.
RSpec.describe Widget do
example do
expect(described_class).to equal(Widget)
end
end
Always start with the problem. Tools don't exist just for fun, they exist because we need them.
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 "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.
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.
I need to either find or write a good readme template with that in mind.
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 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.
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.
>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.
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.
These are all important words for describing projects.
Maybe something at the top along the lines of : what it does, how and then what are the implications.