Write "represents" guideline for HTML elements #1521
Conversation
Also, discourage "indicates" to describe things that are not indicators.
| @@ -180,9 +185,13 @@ Avoid, especially with gerunds. | |||
| For example, prefer the "The feature writes to…" over "The feature provides writing to…." | |||
| ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491)) | |||
|
|
|||
| ##### represents | |||
|
|
|||
| If an HTML element or other type doesn't obviously do anything, then it probably _represents_ something. | |||
There was a problem hiding this comment.
I'd really like to see a Good/Bad example here. I'm still struggling with this one a bunch, and having a couple of examples would help a lot.
There was a problem hiding this comment.
It's hard to think of bad examples, rather I'd treat "represents" as a default for HTML elements which we diverge from when we think some other verb is clearer.
There was a problem hiding this comment.
Yes, @foolip captured my meaning here, as using it as a default. That said, I was able to come up with some examples, so I added them. This necessitated some edits to actual descriptions, of course.
docs/README.md
Outdated
| @@ -162,6 +162,11 @@ Don't use it as a coordinating conjunction; start a new sentence instead. | |||
| For example, this is an example. | |||
| ([#738](https://github.com/web-platform-dx/web-features/pull/738#discussion_r1537762579), [#742](https://github.com/web-platform-dx/web-features/pull/742)) | |||
|
|
|||
| ##### indicates | |||
There was a problem hiding this comment.
It looks like this was motivated by #1436. If it's only popped up once I don't think we need to document it.
Note that it's used in a way allowed by this guideline here:
There was a problem hiding this comment.
OK, I've removed "indicates" from this PR.
| @@ -180,9 +185,13 @@ Avoid, especially with gerunds. | |||
| For example, prefer the "The feature writes to…" over "The feature provides writing to…." | |||
| ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491)) | |||
|
|
|||
| ##### represents | |||
|
|
|||
| If an HTML element or other type doesn't obviously do anything, then it probably _represents_ something. | |||
There was a problem hiding this comment.
It's hard to think of bad examples, rather I'd treat "represents" as a default for HTML elements which we diverge from when we think some other verb is clearer.
github-actions
bot
added
the
feature definition
| Use _represents_ as a default for describing the behavior of HTML elements when no more specific verb makes sense. | ||
|
|
||
| - 👍 Recommended: The `<html>` element represents the top level of an HTML document… | ||
| - 👍 Recommended: The `<br>` element breaks lines in text. | ||
| - 👎 Not recommended: The `<br>` element represents a line break in text. | ||
|
|
There was a problem hiding this comment.
New elaboration on the "represents" guidance
There was a problem hiding this comment.
Not sure I would have used "represents" for the <html> example either...
Thinking how it would compare to <math> and <svg>. Maybe something like:
- The
<html>element is the top level container for documents and iFrames and is referred to as the root element. - The
<math>element is the top level MathML container, used to write a single mathematical formula. - The
<svg>element is the top level SVG container, used in SVG files or for SVG fragments inside an SVG or HTML document.
Also, discourage "indicates" to describe things that are not indicators.
This is inspired by several reviews of HTML elements. Sometimes an element does something (the
<br>element breaks lines), but sometimes they're abstract containers "represents" is a reasonable default.