Obsolete feature naming

[mattgarrish]

Section

https://www.w3.org/TR/epub-34/#app-obsolete

Describe the problem

I don't know that we'll ever find a perfect solution to this, but what to call our obsolete features has been a long-running discussion of names.

As it is, our sections are:

• Obsolete features
  • Outdated features - allowed without warnings but being phased out
  • Deprecated features - allowed with warnings as not recommended anymore

We also still have a class of legacy features that encompass the stuff from EPUB 2 that's allowed in the package document/container to support legacy reading systems (probably not a big need anymore, I'd hope).

Describe the fix or new feature you propose

I'll post a separate comment with one different option, but opening this for anyone who wants to propose alternatives.

[mattgarrish]

From @rdeltour in #2844 (comment) :

Just a nit to pick but I'm not a big fan of the introduction of the "outdated" terminology.

Before we had : "obsolete" = "obsolete but conforming" + "deprecated"
now we have "obsolete" = "outdated" + "deprecated"
I'm not convinced it is much clearer without looking into the details of how these terms are defined. Or maybe it is obvious to English native speakers?

I would find it more intelligible as:

"obsolete" = "obsolete but conforming" + "obsolete and not recommended".
(or the equivalent with "outdated" or "deprecated" instead of "obsolete", I don't have a strong preference here).
i.e. only have one keyword, with the two variants refined by qualifiers.

My reply was:

Ya, I think that's similar to what I originally proposed (html has obsolete but conforming and non-conforming features as its categories) but we opted not to change deprecated yet again.

The issue raised last week is that "obsolete but conforming" is a mouthful. I can live with outdated because it doesn't, at least in English, have the negative connotations of deprecation. Deprecation means you aren't supposed to use whatever it refers to anymore. Outdated means technology or best practice has moved beyond the feature but if you're still old fashioned you can use it.

[mattgarrish]

The other alternative I would suggest is swapping outdated with obsolete, so we get:

• Outdated features
  • Obsolete features
  • Deprecated features

That would maybe use terminology people are more familiar with, although obsolete and deprecated are often seen as synonymous. It feels a bit more natural after seeing the previous swap of terms, but honestly I'm fine either way.

[iherman]

The issue raised last week is that "obsolete but conforming" is a mouthful. I can live with outdated because it doesn't, at least in English, have the negative connotations of deprecation. Deprecation means you aren't supposed to use whatever it refers to anymore. Outdated means technology or best practice has moved beyond the feature but if you're still old fashioned you can use it.

I agree with this comment. Also, "obsolete and not recommended" is even more of a mouthful...

• Outdated features
  • Obsolete features
  • Deprecated features

I can live either way.

[simzy39]

I think the confusion here comes from trying to make a single word carry both conformance status and lifecycle guidance. My preference would be to keep the current three categories, but make their meanings explicit, non-overlapping, and easy to understand without reading multiple definitions.

I would recommend the following terms and definitions:

Outdated features
Features that are fully conforming and allowed without warnings, but which represent older practices. New content is discouraged from using them, but existing content remains valid and interoperable.

Deprecated features
Features that are still conforming, but for which use is discouraged and SHOULD trigger warnings in validation tools. These features may be removed in a future major revision.

Obsolete features
Features that are no longer conforming and MUST NOT be used in new or updated publications.

With this structure:

• Outdated communicates “legacy but acceptable”
• Deprecated communicates “discouraged and on a removal path”
• Obsolete communicates “no longer valid”

I think the spec text would benefit from clearly separating validity from recommendation, ideally with a short introductory paragraph or table that explicitly states, for each category:

• whether the feature is conforming
• whether validators should warn
• whether authors are encouraged to avoid it
• whether removal is planned

That kind of guidance would make the terminology much easier to understand without relying on subtle distinctions in wording alone, and would help authors, implementers, and tool vendors interpret these sections consistently.

[sueneu]

Outdated communicates “legacy but acceptable”
Deprecated communicates “discouraged and on a removal path”
Obsolete communicates “no longer valid”

@simzy39 I love the clarity of these terms and the extended definitions.

ideally with a short introductory paragraph or table that explicitly states, for each category

Maybe we could use icons— with text labels for a11y— at the beginning of a feature section?

[mattgarrish]

I think we might be veering off into discussing how things were in epub 3.3. We've already taken all of the outdated and deprecated features out of the body of the specification so all that remains of them is a listing under their respective classification in the appendix. The only place you'll find mention of these features in the body is in a few content model definitions that still allow them, but those all link to their listing as outdated/deprecated features.

The last issue we can't quite all seem to agree on is the naming. The appendix is called "Obsolete features" even though nothing is actually designated an "obsolete feature" (we don't have features you must not use and by our charter could not add such a classification). It's just a heading that groups the two classifications we actually use "Outdated features", which can still be used but are on their way out, and "Deprecated features", which aren't recommended for use anymore and definitely wouldn't survive into an epub 3 successor format.

I'd love to find a heading for the appendix that doesn't rely on using another feature classification label, like "obsolete" or "outdated", but I haven't had any luck with it. The easiest thing might be to drop the grouping header and have one appendix for the outdated features and another for the deprecated.

[simzy39]

@mattgarrish
You don't need the word 'features' in the heading. It works with either 'Obsolescent' or 'Phasing Out'

[sueneu]

The easiest thing might be to drop the grouping header and have one appendix for the outdated features and another for the deprecated.

Would we still have some indication of the status with in the feature’s section?

For instance, if I was reading about a feature, would I know that it was outdated/obsolete without checking the appendix? It would be burdensome to have to check the appendix for each feature just in case. It would be hard for someone new to the spec to know they have to check the appendix.

[mattgarrish]

would I know that it was outdated/obsolete without checking the appendix?

Yes, definitely! For element content models the classification is immediately after the feature in parentheses, with that status linking to the appropriate appendix section. When the feature is mentioned in the prose, the status precedes it with a link. For example, "The deprecated xyz feature..."

Icons are an interesting idea, but I think plain text will prove a lot simpler, especially if we can keep to one word classifications. Icons aren't ideal for inline text, for example, and then we get into a whole other can or worms figuring out what symbols would be meaningful.

[mattgarrish]

It works with either 'Obsolescent' or 'Phasing Out'

Unfortunately, this is the kind of issue where there are convincing arguments for every proposal, which is the whole crux of this ongoing discussion... 😄

I'm personally still trying to think of something that takes us in a different naming direction, like "Support considerations" or "Usage considerations". That would let the subsections speak for themselves.

[sueneu]

can or worms figuring out what symbols would be meaningful.

You mean you don’t want to talk about the color of our bike shed? 😂 Good point!

I'm personally still trying to think of something that takes us in a different naming direction, like "Support considerations" or "Usage considerations". That would let the subsections speak for themselves.

Maybe we can handle this the way we decided on “roll” Bring up the options at a meeting and take a vote?

@mattgarrish if you’re agreeable, I’ll make a separate discussion about vocabulary and we can gather the options.

[simzy39]

@mattgarrish
I'm not sure if you are intentionally doing this, but you keep settling on plural nouns, which are classificatory, as your appendix title. Also, you've mentioned you would like to let the subsections speak for themselves. I do think 'Obsolescent' works because it is descriptive and not classificatory.

Here is what our suggestions look like and sound like when written out:

E. Obsolete Features
E.1 Outdated features
E.2 Deprecated features

E. Support Considerations
E.1 Outdated features
E.2 Deprecated features

E. Usage Considerations
E.1 Outdated features
E.2 Deprecated features

E. Obsolescent
E.1 Outdated features
E.2 Deprecated features