disband "Terms and Definitions"

[jmdyck]

I'd like to suggest that 4.3 Terms and Definitions ["TaD"] be disbanded. That is, each of its definitions should be relocated to somewhere in the text where it makes sense in context. (And the term should be put in a <dfn> element.)

Since the spec moved to github, no terms have been added to TaD. I suspect this is because people like 'in-context' definitions and don't see a point to putting them in TaD instead (if they even consider the possibility).

I was under the impression that Ecma required all of its standards to have such a clause, but apparently not. E.g.,

• ECMA-402 ES Intl doesn't have one.
• ECMA-404 JSON doesn't have one.

In ECMA-367 Eiffel, the "Definition" clause simply says:

All the Eiffel-specific terms used in the Standard are defined in paragraphs labeled “Definition”.

In ECMA-408 Dart, " Terms and Definitions" just says:

Terms and definitions used in this specification are given in the body of the specification proper. Such terms are highlighted in italics when they are introduced, e.g., ‘we use the term /verbosity/ to refer to the property of excess verbiage’.

If, for some reason, Ecma wants ECMA-262 to have a TaD clause, the latter seems like a nice choice.

[bterlson]

I agree. There are also few inbound references to that clause so moving them around should be easy. I'd take a PR for this (or maybe @bmeck / @ljharb could take a stab).

[jmdyck]

There are also few inbound references to that clause so moving them around should be easy.

Are you saying that you wouldn't require preservation (via oldids) of the sec-foo ids of TaD's subclauses?

[allenwb]

Before jumping into this I think you should think a bit about its impact on new readers of the specification. In my experience, reading through a "Terms and Definition" section of a specification is a good way to get an initial sense of what the specification is all about before digging deeper into the normative material of the specification. In support of this, I'll point out that the reason this clause exists in Ecma specifications and many standards produced by other standards organizations is that ISO's "standard for standards" specification includes it as a standard (but optional) clause of ISO standards. There is also a relatively long annex that describes how to write and format the definition that go into that clause. I'll speculate that decades of experience of with what has proven useful to have in standards documents might have something to do with why they bothered to include that clause in their overall document design.

Another concern is unless we retroactively and in the future are very careful to make sure that every use of a defined term is hyperlinked to its definition then there will be no easy way for a reader to lookup an unlinked term. Admittedly this is already the case in that we have defined terms that that are not included in "Terms and Definitions". The other side of this is that some formally defined terms (perhaps "object" falls into this category) are used so frequently that formatting them as hyperlinks may actually hurt readability of the specification.

Perhaps we could replace the current "Terms and Definitions" content with a table or list of terms with each one hyperlinked to its definition.

This proposal is basically all about improving the usability of the specification. And that a good goal. But how do we know that this will actually improve usability? Are we going to do A/B testing?

Finally, in the past we have generally asked for full TC39 consensus before making major structural changes to the specification. I note that this patch is simply labeled as "editorial change". It seems to me that at the very least it should have a "need consensus" label and perhaps should be part of a broader discussion of specification usability issues and whether and how we should go about improving usability.

[jmdyck]

...I think you should think a bit about its impact on new readers of the specification. In my experience, reading through a "Terms and Definition" section of a specification is a good way to get an initial sense of what the specification is all about before digging deeper into the normative material of the specification.

New readers could still get this sense from 4.2 ECMAScript Overview.

I'll speculate that decades of experience of with what has proven useful to have in standards documents might have something to do with why [ISO] bothered to include that clause in their overall document design.

And such a clause might be quite useful for many standards. But it isn't necessarily useful for ECMA-262.

we [already] have defined terms that that are not included in "Terms and Definitions".

In fact, the majority of the spec's terms are not defined in TaD. (So, if this were going to be a problem, we might expect it to have been a problem already. But I don't think anyone's ever complained that a term is not defined in TaD.)

But how do we know that this will actually improve usability? Are we going to do A/B testing?

Have we done A/B testing on any other change that affected usability? Does any spec-producing body do A/B testing re usability? Mostly, I think they just trust the judgment of the editor(s).

[This issue] perhaps should be part of a broader discussion of specification usability issues and whether and how we should go about improving usability.

Sounds good to me.

[allenwb]

New readers could still get this sense from 4.2 ECMAScript Overview.

Probably not. 4.2 is essentially a short introduction to the JavaScript language, not an introduction to the concepts and terminology used to specify the language. An intro to the basic language concepts was probably necessary in 1997. Probably not so much today.

Clause 4 contains some of the oldest material in ECMA-262. It is long over due for a complete rethinking and rewrite. What does a modern reader need in 2019 to ease them into using ECMA-262? I'd sooner see effort going into addressing that rather than just shuffling definitions into different parts of the specification.

[jmdyck]

4.2 is essentially a short introduction to the JavaScript language

Well, you wanted "an initial sense of what the specification is all about". Why shouldn't that be a short intro to the language?

not an introduction to the concepts and terminology used to specify the language.

Huh? 4.2 introduces lots of concepts and terminology -- about half of the terms defined in TaD, plus several not defined in TaD. Moreover, it does so more readably than TaD does.

And for a different sense of "concepts and terminology used to specify the language", there's also 5 Notational Conventions.

Clause 4 [...] is long over due for a complete rethinking and rewrite. [...] I'd sooner see effort going into addressing that rather than just shuffling definitions into different parts of the specification.

It doesn't have to be either/or. The committee might decide that it wants both the complete rethink and the definition-shuffling. The rethink might take longer, but I doubt there's any reason why the disbanding of TaD would need to wait for it.

[michaelficarra]

Editors agree that we should disband the T&D section. #3146 is a small step in this direction. @jmdyck has volunteered to do this work.