Remove draft terms

[mattgarrish]

Describe the problem

Ten years after we stopped working on edupub we still have all the terms from the last draft in the structural semantics vocabulary. It's long past time we did something about them.

Having draft terms just sows confusion as noted in https://github.com/w3c/epubcheck/issues/1617

Describe the fix or new feature you propose

I proposed a number of years ago in https://github.com/w3c/epub-specs/issues/1019 that we incorporate them as full terms in the vocabulary, but that didn't go anywhere.

Since these are all edupub terms and remain defined in the last edupub draft, can we instead just remove them? If someone wants to use terms from edupub, removing them from the structure vocabulary doesn't change anything - epubcheck can continue to treat them as not fully recognized terms. We don't need them in the main vocabulary.

I'd only suggest that we keep the terms that ended up having parallels in DPUB-ARIA - and drop the draft status from them. Those terms are:

• abstract
• backlink
• biblioref
• credit
• credits
• glossref
• pullquote

[mattgarrish]

And, interestingly, edupub doesn't even refer to the main structural semantics vocabulary for its proposed new terms.

Section 4.4 links to an old google doc draft of a separate edupub structural semantics vocabulary.

So removing the definitions from the SSV will have no effect on the old edupub draft.

[iherman]

I am a bit confused of what we are talking about. The W3C Note contains a separate subsection on educational content; however, my impression is that you propose to remove all but some of the terms listed in the original IDPF draft. Is that correct?

I am not against this move in principle, but that raises the question about what the criteria are for keeping terms in the structural vocabulary note in the first place (whether they are originated in EDUPUB or not). I would presume it should be a matter of usage of those terms in practice; do we have any data about those? Actually, do we have a reliable list of the terms we are talking about (i.e., that are not coming from EDUPUB?)

(Luckily, this is WG Note, we can manipulate it at our hearts' content…)

[mattgarrish]

Everything that's currently marked as a draft term came from edupub. It's not just the ones listed under the educational content section.

They were duplicated into the main structure vocabulary as eventually it would have avoided having more than one default vocabulary for epub:type, although how much that would have mattered is debatable given all the other weird vocabulary stuff we've done.

Could we cull more from the vocabulary, sure, but it's like the defunct reserved prefixes - is it worth the effort of finding out who and how widely the 130 or so terms in the vocabulary might have been used? And how will we know if we've captured enough feedback? I'd love to see the indexing terms gone when we know the specification has never been implemented, but I'm sure someone went and used them.

Having them permanently linger as draft terms is a bit absurd when we know edupub isn't being revived, and since the consensus last time I asked was to not make these permanent, the only other logical thing to do with them is turf them out. It has no practical effect on anything because these were always edupub terms and they remain defined in the last working draft of that specification.

We also shouldn't be giving authors the impression that these are terms we are actively working on by keeping them and calling them drafts. I'd be fine adding a note explaining why the draft terms were taken away and pointing people to the last edupub draft if they want to continue to use them, as at least that way they know what they're getting into.

[mattgarrish]

Oh, and why I'd keep the ones with matching dpub-aria roles is that for accessibility checking we were suggesting to always pair the corresponding role with the epub:type. That's likely led to those terms being used more than the other edupub ones.

They're also all general terms and not education-specific.

[mattgarrish]

If we wanted to remove only the very obviously educational/testing specific stuff in section 10 (some of it predated edupub so we can't drop it all), that would also have us add:

• case-study
• keywords
• label
• ordinal
• seriespage
• toc-brief

I'm more interested in finally dropping the draft labels than concerned about adding more terms. They're all harmless in the end.

[iherman]

Sorry to be a pain @mattgarrish, I just want to have a clear message on what we do and why on the document. You say:

Everything that's currently marked as a draft term came from edupub.

but that does not mean all entries that come from EDUPUB are labelled as a draft, see, for example, learning-objective, learning-resource, noteref (which are all listed in the EDUPUB note). I must admit, I have no idea why certain terms were labeled as drafts and others were not.

A clear message for me would be to say: we clean up the spec, and we remove all terms that are currently marked as "draft" (should it be "draft" or "deprecated"?). For the rest, as you say, it is not worth the effort to find out actual usage. This would probably remove a large portion of the EDUPUB terms (with a few exceptions).

[mattgarrish]

but that does not mean all entries that come from EDUPUB are labelled as a draft

Every new term created by the edupub group is a draft, yes, but this is what I was mentioning above about the structure vocabulary having some educational/testing terms in it before the edupub work started. The incompleteness of the vocabulary for educational publishers was one of the complaints that led to edupub.

The edupub structural vocabulary took all the useful terms that already existed in the main SSV and added onto them, so we can't drop everything that would be considered educational/testing, no.

[iherman]

So... can say: we remove all entries that are marked as 'draft' or 'deprecated'?

[mattgarrish]

we remove all entries that are marked as ... 'deprecated'?

Ya, that's a tough call. We used to have a "revision policy" section in the IDPF version that said we could deprecate terms but we would never remove them from the vocabulary.

That didn't get ported into the W3C version, but I wonder if we should adhere to the same principle? It didn't apply to draft terms because we said any use of them should be considered experimental. Only terms with no label were stable.

We might want to restore some of these statements about how to understand the document.

[iherman]

we remove all entries that are marked as ... 'deprecated'?

Ya, that's a tough call. We used to have a "revision policy" section in the IDPF version that said we could deprecate terms but we would never remove them from the vocabulary.

That didn't get ported into the W3C version, but I wonder if we should adhere to the same principle? It didn't apply to draft terms because we said any use of them should be considered experimental. Only terms with no label were stable.

I am pretty neutral on this, to be honest; I simply do not have the grasp on what the consequences would be, ie, how frequently those deprecated terms are/were used in practice.

Why don't we do the following?

• Let us create a PR with all draft entries removed. That has a clear story even for those who have not been around for EDUPUB, ie, for those for whom that reference does not really resonate
• Raise the question on the deprecated stuffs as part of the PR
• We get the chairs to put the PR on the agenda of a WG discussion and see where it goes...

[mattgarrish]

Ya, I'll put something together based on what we've discussed so far so everyone can review the changes.

I'll probably keep the first set I listed above for the first review because, as you noted, they're also referenced from dpub-aria. Taking them out has more implications than just what might have been authored and whether epubcheck continues to accept the terms as it has to date.