docs(rules): usage argumentation
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 3.3k
- Forks
- 474
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 12
Description
1. Summary
It would be nice, if HTMLHint documentation will contain arguments, why HTMLHint users must use specific rules.
2. Argumentation
“Must” in The script tag can not be used in head., Id and class value must meet some rules: underline, dash, hump. is not argument. The documentation does not show the reasons. Users should know “Why must”?
3. Example of expected behavior
As for CSSLint wiki. Examples:
adjoining-classesrule use, because Internet Explorer 6 doesn't support adjoining classesfallback-colors, because Internet Explorer 8 doesn't supportrgba()hsl()orhsla()
HTMLHint wiki doesn't contain similar argumentation.
4. Specific rules
At first, I want to know argumentation for these rules.
4.1. head-script-disabled
Most popular Stack Overflow answer with 1608 stars at March 2019:
The current state-of-the-art is to put scripts in the
<head>tag and use theasyncordeferattributes. This allows your scripts to be downloaded asap without blocking your browser.
Script tag must be used in head.
4.2. id-class-value
BEM — the most popular CSS methodology use underlines and dashes both. Example from BEM quick-start:
<!-- `search-form` block -->
<form class="search-form">
<!-- `input` element in the `search-form` block -->
<input class="search-form__input">
<!-- `button` element in the `search-form` block -->
<button class="search-form__button">Search</button>
</form>
Users don't need use underlines or dashes.
5. Do not offer
Yes, I know, that I can enable/disable/modify specific HTMLHint rules. My question not about it.
Thanks.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the HTMLHint wiki pages for Head-script-disabled and Id-class-value, along with the cited Stack Overflow and BEM references. Add clear, evidence-based rationale to those rule pages, explaining when the rules are useful without presenting their current wording as universally required.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100