Custom elements section contain too much tutorial-like contents #1642

Open
rniwa opened this Issue Aug 9, 2016 · 15 comments

Projects

None yet

4 participants

@rniwa
Collaborator
rniwa commented Aug 9, 2016 edited

Section 4.13.1. contains a lot of opinionated tutorial-like paragraphs and contents. I don't think we want to turn the HTML specification into a tutorial or a place in which people express their political opinions.

Given that we've repeatedly opposed to having customized builtin elements in the first place, I find it rather offensive to have a spec text arguing why customized builtin elements are better than autonomous custom elements without giving full disclosure of the current discussion.

Those arguments are better made during spec discussions, not in the actual spec.

@rniwa
Collaborator
rniwa commented Aug 9, 2016
@domenic
Member
domenic commented Aug 9, 2016

Hi @rniwa, can you point to any inaccurate sections in the spec? It's not meant to be offensive, just factual. We're happy to correct any errors.

There's a long history of introduction sections that explain to web developers how to use a feature and the consequences of using it; remember that the HTML spec is not only for implementers. You can see other examples in e.g.:

and others.

I don't think we'll remove these sections or the content in them, but as I said, I'm happy to correct any factual inaccuracies ("bugs") you find.

@rniwa
Collaborator
rniwa commented Aug 10, 2016

For example, the last paragraph in the introduction is more of a political statement about "The Extensible Web Manifesto" than an explanation of any feature:

Custom elements are part of a larger effort to "rationalize the platform", by explaining existing platform features (like the elements of HTML) in terms of lower-level author-exposed extensibility points (like custom element definition). Although today there are many limitations on the capabilities of custom elements—both functionally and semantically—that prevent them from fully explaining the behaviors of HTML's existing elements, we hope to shrink this gap over time.

The title of 4.13.1.3 "Drawbacks of autonomous custom elements" needs to be renamed to something like "Accessibility considerations of autonomous custom elements".

The last two paragraphs of the section reads like an opinion piece about customized built-in element versus autonomous custom elements:

Even with this rather-complicated element definition, the element is not a pleasure to use for consumers: it will be continually "sprouting" tabindex and aria-* attributes of its own volition. This is because as of now there is no way to specify default accessibility semantics or focus behavior for custom elements, forcing the use of these attributes to do so (even though they are usually reserved for allowing the consumer to override default behaviour).

In contrast, a simple customized built-in element, as shown in the previous section, would automatically inherit the semantics and behaviour of the button element, with no need to implement these behaviours manually. In general, for any elements with nontrivial behavior and semantics that build on top of existing elements of HTML, customized built-in elements will be easier to develop, maintain, and consume.

A single sentence saying that "In contrast, a simple customized built-in element, as shown in the previous section, would automatically inherit the semantics and behavior of the button element, with no need to implement these behaviors manually" can replace the entire paragraphs.

@domenic
Member
domenic commented Aug 10, 2016

For example, the last paragraph in the introduction is more of a political statement about "The Extensible Web Manifesto" than an explanation of any feature:

Hmm. I think it's important to state the goals of the feature and historical background. A similar paragraph has been present since the earliest drafts of custom elements.

The title of 4.13.1.3 "Drawbacks of autonomous custom elements" needs to be renamed to something like "Accessibility considerations of autonomous custom elements".

Why? Are these not drawbacks? There are more drawbacks than just accessibility discussed here, as well.

A single sentence saying that "In contrast, a simple customized built-in element, as shown in the previous section, would automatically inherit the semantics and behavior of the button element, with no need to implement these behaviors manually" can replace the entire paragraphs.

I don't think it can. That removes valuable information:

  • the sprouting attributes and the inability to specify default accessibility semantics and focus behavior
  • the need to use attributes to do so
  • the fact that those attributes are normally used by the consumer, not the producer
  • the fact that it will be easier to develop, maintain, and consume a counterpart customized built-in element

We cannot remove that information.


Again, I was hoping you would reply with some actual factual bugs in the text or example code we could correct. Have you found any?

@rniwa
Collaborator
rniwa commented Aug 10, 2016

The section 4.13.1.4 Upgrading elements after their creation says:

Upgrades enable scenarios where it may be preferable for custom element definitions to be registered after relevant elements has been initially created, such as by the parser. They allow progressive enhancement of the content in the custom element. For example, in the following HTML document the element definition for img-viewer is loaded asynchronously

The sentence about progressive enhancement doesn't add any new information of the feature.

Upgrades enable scenarios where it may be preferable for custom element definitions to be registered after relevant elements has been initially created, such as by the parser. For example, in the following HTML document the element definition for img-viewer is loaded asynchronously

would provide just as much information without alluding to any politically motivated buzzwords.

@domenic
Member
domenic commented Aug 10, 2016

I am kind of surprised by your willingness to call specification text, written in good faith, "politically motivated". Can we refocus the discussion on actual factual errors in the spec that you have found, instead of your categorizations of what kind of speech is being presented?

@rniwa
Collaborator
rniwa commented Aug 10, 2016

For example, the last paragraph in the introduction is more of a political statement about "The Extensible Web Manifesto" than an explanation of any feature:

Hmm. I think it's important to state the goals of the feature and historical background. A similar paragraph has been present since the earliest drafts of custom elements.

And I would have objected to have that kind of sentence being in the spec as well. I was simply focusing on other aspects of the spec earlier.

The title of 4.13.1.3 "Drawbacks of autonomous custom elements" needs to be renamed to something like "Accessibility considerations of autonomous custom elements".

Why? Are these not drawbacks? There are more drawbacks than just accessibility discussed here, as well.

You may see it as drawbacks because you believe in the feature. This is precisely why I'm saying this section is about highly opinionated.

A single sentence saying that "In contrast, a simple customized built-in element, as shown in the previous section, would automatically inherit the semantics and behavior of the button element, with no need to implement these behaviors manually" can replace the entire paragraphs.

I don't think it can. That removes valuable information:

  • the sprouting attributes and the inability to specify default accessibility semantics and focus behavior
  • the need to use attributes to do so
  • the fact that those attributes are normally used by the consumer, not the producer
  • the fact that it will be easier to develop, maintain, and consume a counterpart customized built-in element
    We cannot remove that information.

Why? That doesn't explain anything useful to the author. We can list hundreds of features that are lacking from the Web in each spec we have but we don't do that because they don't provide any useful context that merit authors.

@rniwa
Collaborator
rniwa commented Aug 10, 2016

I am kind of surprised by your willingness to call specification text, written in good faith, "politically motivated". Can we refocus the discussion on actual factual errors in the spec that you have found, instead of your categorizations of what kind of speech is being presented?

The problem I have is precisely that. This entire section reads extremely opinionated in favor of customized built-in elements. I'd like the spec to only focus on facts, not some opinion about which feature does what well.

@domenic
Member
domenic commented Aug 10, 2016

And I would have objected to have that kind of sentence being in the spec as well. I was simply focusing on other aspects of the spec earlier.

OK. I guess we will just have to agree to disagree about the value of such introductory text.

You may see it as drawbacks because you believe in the feature. This is precisely why I'm saying this section is about highly opinionated.

I don't follow. They are drawbacks because they are disadvantages or problems for authors using the feature, and should be pointed out as such.

Why? That doesn't explain anything useful to the author. We can list hundreds of features that are lacking from the Web in each spec we have but we don't do that because they don't provide any useful context that merit authors.

It does, because it contrasts it with alternative mechanisms. Authors are always well-served by explaining to them what their options are.

The problem I have is precisely that. This entire section reads extremely opinionated in favor of customized built-in elements. I'd like the spec to only focus on facts, not some opinion about which feature does what well.

I'm sorry you see it that way. It's just explaining the facts and contrasts between the approaches. If you can't find any factual inaccuracies in its descriptions, then I don't think there's anything for us to change here.

@rniwa
Collaborator
rniwa commented Aug 10, 2016

Note that I have no doubt you wrote it in good faith. The problem is that it doesn't read factual and neutral from our perspective because our opinion is that customized built-in elements shouldn't even be a thing.

@domenic
Member
domenic commented Aug 10, 2016

Note that I have no doubt you wrote it in good faith. The problem is that it doesn't read factual and neutral from our perspective because our opinion is that customized built-in elements shouldn't even be a thing.

I appreciate that very much. And if we were writing a spec in which they were not a thing, I am sure the section would be different. But since the working agreement is to keep them in the spec, it's important to compare and contrast them. Perhaps it is best to revisit these questions after we've seen what the implementation progress is and whether they stay a thing or not.

@rniwa
Collaborator
rniwa commented Aug 10, 2016

Okay, fair enough. My preference was to add these compare & contract section afterwards instead but we can keep it around for now since I don't think this is the most important issue at hand.

@rianby64

I enjoy to read the history that made the current version to be possible. Yeah, is not my business, but if I read an example from W3C or WHATWG then I'll feel more confident when coding. And Custom Elements in my opinion is: the beginning of the frameworks' end.
Please, don't remove the examples, the author's opinions or similar. Every word matters! Even if it sounds like a tutorial.

@rniwa
Collaborator
rniwa commented Aug 13, 2016 edited

Please, don't remove the examples, the author's opinions or similar. Every word matters! Even if it sounds like a tutorial.

The problem is that a specification is a collaborative work, which needs to be written upon consensus. As far as this matter is concerned, there is no consensus to include such an introduction.

@tabatkins
Collaborator

Consensus != unanimity. You can have consensus with objections.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment