README doesn't explain the rule
ematipico opened this issue · comments
I read the README extensively and it was difficult for me to understand what this plugin does.
At the beginning it says that's a rule for deprecated code, but it's not easy to understand what's deprecated code.
The rest is about installation and set up.
I ended up looking at the tests.
Maybe before the installation header, the documentation should show an example of what the rule does.
Readme states in the first line An ESLint rule that reports usage of deprecated code..
And "usage of deprecated code" is exactly that - any deprecated code that is being used.
I do not see any need to explain what a deprecated code means, people can google it for themselves if they do not understand the concept.
Also this rule is used/looked up by people who most likely already know what they are trying to achieve so this would be useless in 99% cases.
Let's keep readme clean and short.
If you still think it makes sense to add explainer of deprecated code we can add it in a collapsible spoiler so it does not occupy much space - in this case feel free to open a PR with suggested change and examples you feel are missing 😊
Thank you for your reply.
Since the README is being used as the only source of documentation, I believe it should at least provide:
- a brief explanation of what's a deprecated code in a TypeScript code base
- show some examples of what the rule catches
The documentation should at least say that it leverages the @deprecated JSDoc, used by IDEs and TS to mark bindings and functions as deprecated.
I'm fine with adding that to the docs under a collapsible spoiler.
Would you like to draft a PR with the text?
I was also looking for this - it's not clear what APIs are being targeted here (browser APIs? TypeScript APIs? Node.js APIs?)
Would suggest not collapsing these details - these are important for people deciding whether this makes sense for their project
I was also looking for this - it's not clear what APIs are being targeted here (browser APIs? TypeScript APIs? Node.js APIs?)
Would suggest not collapsing these details - these are important for people deciding whether this makes sense for their project
I do not think you actually understood the purpose of this rule, deprecated code does not have any specific target, any usage of any deprecated code in your codebase will be reported by this rule and it includes any code you write as long as it is a js/ts.
To me it seems you guys are more on the outside of the JS ecosystem and hence you have some confusion but for the majority of people who are familiar with JS this rule is perfectly clear because we've only got this issue raised today while it existed for more than 4 years now.
Again I'm perfectly fine to add extra details about what the deprecation is so you are free to open a PR with the change and we can all review it and have it in the readme. And we don't have to collapse it, just create an extra section after the installation should be just fine.
To me it seems you guys are more on the outside of the JS ecosystem
I've been working in Node.js, React, TypeScript and Next.js ecosystems for years and am an active contributor all over the place there. I also am teaching many new people per year to learn to use JavaScript and TypeScript (both frontend and backend), and I'm sure that the readme would also be unclear to most or all of them.
but for the majority of people who are familiar with JS this rule is perfectly clear
I think this is a big assumption to make, with two separate random people taking the time within 24 hours to provide feedback representing data points which refute this.
I do not think you actually understood the purpose of this rule
This is indeed the problem - it is not self-explanatory. Like many obscure tech projects, it needs some marketing :)
Again I'm perfectly fine to add extra details about what the deprecation is so you are free to open a PR with the change and we can all review it and have it in the readme. And we don't have to collapse it, just create an extra section after the installation should be just fine.
Great, I created this PR:
Keeps the wording very short, but gives a bunch of examples with screenshots:
More confused users here:
Even Cory House, pretty prominent JS trainer in the industry, got it wrong - he said it was "for packages", when it's more than that.
So yeah, probably this needs some clarification in the readme.
To be honest:
I use this rule for multiple years now. It's somehow clear to me what it does after trying it. I'm happy with it! ❤️
But it really helps to have a README that gives some explaination about what it exactly does.
When I pick a random ESLint rule I will always find a code example that explains the rule.
So I agree with @karlhorky. I really like to have some nice marketing.
Currently the only hint what it does is it's name and following sentence
An ESLint rule that reports usage of deprecated code.
🎉 This issue has been resolved in version 3.0.0 🎉
The release is available on:
Your semantic-release bot 📦🚀