Comments (44)
I agree that it would be good to put some thought into UI/UX for this. I'm not sure if colors are the best way (considering r/g colorblind folks), but perhaps it could be used in conjunction with a larger redesign at some point? I'd love to see some consistency between how options are explained and examples are given. I just don't know how that design should look.
from archive-website.
Colors were just the most obvious way I came up with to solve the problem. I agree that this idea is most useful in conjunction with other measures. Currently, we are all treated as colorblinds (sort of).
If you want to tackle it at a more general level, perhaps a table is a better way to display those qualities:
Rule: yoda
default: "never"
Configuration | validates | fails |
---|---|---|
"yoda": [2, "never"] |
if (color === "red") {} |
if ("red" === color) {} |
This would also solve the problem that much space is wasted on most screen sizes due to full-width code blocks.
from archive-website.
The problem becomes how to generate such changes automatically. It's unlikely we will get a volunteer to reformat every for by hand, so what can be done such automation?
from archive-website.
If we can find a solution for this that will also solve the remaining blocker in my mind on eslint/eslint#2271 (how do we lint valid examples but only check invalid examples for syntax?), then we could solve this at the same time we (likely meaning "I") go through and use configuration comments (related discussion eslint/eslint#3208) for all the examples.
from archive-website.
Is it just a matter of wrapping code blocks with a div of an appropriate class? I don't know how the file loader / documentation linting works, but that could potentially be used at least for styling.
from archive-website.
And @btmills I would be happy to change docs to use configuration comments. Your mind/time is better utilized on less tedious activities.
from archive-website.
I don't think it's a matter of wrapping the code in a div. We write everything in MD format. And code blocks are converted into <pre>
tags by jekyll. I don't actually know how we can achieve valid vs. invalid styles with .md
from archive-website.
<div class="passing">
// md code block here
</div>
Is valid markdown, and the background can be styled with:
.passing pre {
background:green;
}
I've tested it out in my blog (which also uses markdown) and it worked, and can try it on the this repo tonight.
from archive-website.
@IanVS If your example turns out to be working, would you agree with my idea to use tables? Basically, It'd be the same approach:
<div class="yep-nope-table">
// md table here
</div>
// css:
.yep-nope-table td:first-child { /* config block */ }
.yep-nope-table td:first-child + td { /* yep block */ }
.yep-nope-table td:first-child + td + td { /* nope block */ }
from archive-website.
I can try tables as an experiment, but in my experience markdown tables are kind of a pain to work with. I do think in general the result might look nicer and be clearer, but we could run into the issue of wrapping lines, which is always ugly in code examples. Also, changing to tables would require much more drastic changes to all of the rule docs. I'll try it out though.
from archive-website.
Just to reiterate: anything manual is not a good solution. These are manual solutions which mean we are going to have to manually convert everything and also manually enforce their usage on pull requests. In both cases, this is a lot of work, so I'm skeptical this is a good direction.
from archive-website.
What if the examples in the docs were all live? If the demo could be made into something reusable, then invalid examples would have the actual error messages right there.
from archive-website.
And how would you automate that?
from archive-website.
For illustration, I'll borrow an example from eqeqeq:
The following patterns are considered okay and do not cause warnings:
/* eslint eqeqeq: [2, "smart"] */
typeof foo == 'undefined'
'hello' != 'world'
0 == 0
true == true
foo == null
The following patterns are considered warnings with "smart":
/* eslint eqeqeq: [1, "smart"] */
// comparing two variables requires ===
a == b
// only one side is a literal
foo == true
bananas != 1
// comparing to undefined requires ===
value == undefined
npm test
runs the linter on the docs using the Markdown preprocessor. Makefile.js
will fail the build on errors (parse errors in valid and invalid examples and lint errors in the valid examples), and it will suppress warnings in the docs (from lint warnings in the invalid examples). This reduces our manual workload on PRs from manually checking and verifying examples for both syntax and linting down to making sure examples have a configuration comment that enables the rule.
The live demo part is hazier, as I don't know how the page build process works. @xjamundx is there (or could there be, with the work you're doing) a way to load a demo on code blocks within the page?
from archive-website.
Interesting. And how do we update the already existing docs?
from archive-website.
I've volunteered to update them.
from archive-website.
Cool :)
from archive-website.
I don't think it's a matter of wrapping the code in a div.
You're right, this doesn't work in redcarpet
, Jekyll's markdown processor.
from archive-website.
@nirazul @IanVS @nzakas @btmills @ilyavolodin
Can you think of any additional objectives which are relevant to this issue?
- Given incorrect or inconsistent code, find a rule (and its options) to prevent it.
- Given a rule (and its options) in the configuration for a project, write correct code.
What do you think about the following pattern for the sentence preceding an example of code?
- The sentence begins with Examples of.
- Adjectives incorrect and correct decribe the code to avoid confusion with rule configuration error levels: warning or error.
- Omit any verb to avoid the passive voice: are considered.
- Make the rule configuration explicit:
- Examples of incorrect code if you turn on the rule:
- Examples of incorrect code for the default
"always"
option: - Examples of incorrect code for the
"never"
option: - Examples of incorrect code for the
{"builtinGlobals": true}
option: - Examples of incorrect code for the
browser
environment and the{"builtinGlobals": true}
option: - Examples of incorrect code for the
{"anonymous": "always", "named": "never"}
option: - Examples of incorrect code for the
{"anonymous": "never", "named": "always"}
option:
Because the sentence includes configuration, what do you think if we omit punctuation in h3 headings for options to make a potential table of contents easier to scan?
Rule Details
Options
always
never
anonymous
named
When Not To Use It
Related Rules
Version
Resources
Considering the examples (in several following comments) which contrast baseline grammar and formatting with suggested changes, how well do you think the suggestions support the objectives?
ESLint members: and how realistic do you think it is for future editors of rule pages (including first-timers) to follow the suggested pattern (to a reasonable extent) after the initial rewriting, which I am willing to do?
from archive-website.
Rule has no options: no-console
from archive-website.
The default value of an option: consistent-this
from archive-website.
A second set of examples for an option: consistent-this
from archive-website.
Another value of an option: space-before-function-paren
from archive-website.
An object value of an option: space-before-function-paren
from archive-website.
@pedrottimark I like it. I never cared much for "patterns are considered problems" I also like green/red backgrounds too. Maybe we can combine those two?
from archive-website.
I think the green/red problem is a technical one. I haven't found a way to accomplish it, but would love it if we could do at least some subtle shading differences.
from archive-website.
Let’s take a background distinction as part of the solution and trust that we will find a way. Just saw some resources for accessible color contrast ratios, so will make some example pictures to discuss.
In addition to distinguishing incorrect from correct, readers can quickly distinguish these examples from any general examples of code or configurations.
A question which I forgot to ask: If only some lines in a code example require es6 environment, what do you think about separating them? Compare the following to the preceding picture:
from archive-website.
I think in the scope of a larger page, having a bunch of smaller wells might be slightly disconcerting. We should also think about possible future were we will support ES7 as well and possibly TypeScript/Flow. That might be just too many wells to deal with.
from archive-website.
Good point that we need to limit the total visual complexity.
- The lighter background for inline code has made some pages more readable for my eyes. #202
- That reminds me to ask how likely the text of code examples might have coloring in the future, because that affects how much background color or pattern will be reasonable. #194
from archive-website.
I'll try to do kramdown upgrade this week, that might bring syntax highlighting, but I'm not 100% sure.
from archive-website.
@ilyavolodin any luck with Kramdown?
from archive-website.
I tried it locally, and found two major issues. Code fences were not working and H1 headers were missing on rule docs. Code fences just required config switch, but H1 headers require modification of our build script. We do not leave empty line before H1s, so they don't render correctly. I'm not sure if there are any more issues, I've been pretty busy the last few days and haven't had the chance to look into it more.
from archive-website.
The following comments have pictures for your feedback about how background color could help people quickly see whether code is an incorrect, correct, or general example.
After the example sentences become consistent, a possible solution to the technical problem is replace rules in the doc.html layout file:
replace: '<p>Examples of <strong>incorrect</strong> code', '<p class="incorrect">Examples of <strong>incorrect</strong> code'
replace: '<p>Examples of <strong>correct</strong> code', '<p class="correct">Examples of <strong>incorrect</strong> code'
corresponding to CSS rules:
p.incorrect + div > pre { background-color: … }
p.correct + div > pre { background-color: … }
from archive-website.
Distinguish general code in the introduction of no-shadow from incorrect code:
from archive-website.
Distinguish incorrect code from correct code for the default option of comma-dangle:
from archive-website.
Distinguish incorrect code from correct code in adjacent options of no-shadow:
from archive-website.
That looks nice, and might work in terms of markup. Although it means we need to go and put paragraphs with classes around each code example. I'm not sure you can do that with markdown.
from archive-website.
I was thinking the replace rules take effect after the conversion from markdown to HTML?
So that the only requirement in the content is consistency in the beginning of the sentence.
Imitating the following:
replace: '(recommended)', '<span title="recommended" aria-label="recommended" class="glyphicon glyphicon-ok"></span>'
replace: '(fixable)', '<span title="fixable" aria-label="fixable" class="glyphicon glyphicon-wrench"></span>'
from archive-website.
You are right, replace kicks in after conversion. Sorry, didn't notice that you mentioned replace. That might work
from archive-website.
I'll try to do this over the weekend and see if it works.
from archive-website.
Here is the CSS I used to make those picture:
p.incorrect + div > pre { background-color: hsl(0,100%,96%); }
p.correct + div > pre { background-color: hsl(120,100%,96%); }
from archive-website.
What do you think about this blue/yellow color contrast, which is more accessible than red/green?
Here are the recommended changes:
- inline code: black on light gray like GitHub, instead of ESLint theme lavender (not in this picture)
- generic pre: light gray like GitHub
- incorrect pre: ESLint theme lavender because this is the “lint”
- correct pre: ivory
from archive-website.
While I understand that red/green is less accessible to some, it's much more standard to most. I think I would just stick with light red/green for incorrect/correct examples.
from archive-website.
I think red/green is okay, especially since we are not relying on the color coding. We've all made it this long without it, after all.
from archive-website.
Related Issues (20)
- Example for linter.defineParser uses old "parse" API HOT 1
- More documentation on conflicting fixes HOT 4
- Update fetch sponsors script
- Missing Substack logo HOT 1
- Add date posted for blog posts HOT 9
- Add a way to manually add sponsors HOT 1
- Docs: Add emoji and notice to indicate which rules provide suggestions HOT 1
- Proposal: Split up website HOT 2
- Cleanup the rules list in Rules Configuration of Demo HOT 7
- add ecmaversion "latest" in demo HOT 1
- Update: Add authors to newer blog posts
- Update blog post front matter HOT 12
- Add warning for suggested changes to rule docs HOT 10
- Make sure every blog post has a teaser HOT 7
- Disable anonymous proxy HOT 2
- Search results are not scrollable HOT 1
- Authors not displayed on blog posts with more than 1 author HOT 2
- Fix blog post authors HOT 2
- Build broken HOT 2
- Please provide documentation in yml format as well HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from archive-website.