Naming and maturities of separate documents holding registry tables only

[frivoal]

Commit 753bcb3 introduces the possibility of publishing the registry tables in a document that is separate from the one that holds the registry definitions.

There were potentially several ways to do this, particularly when it comes to naming things. The commit above picked one particular approach that seemed the simplest, but there are other ways of going about this.

First, note that when a single document holds both the registry definitions and the registry tables, it is a registry report, with various maturities like Draft Registry, Candidate Registry, W3C Registry, Obsolete Registry, etc.

Open questions are:

1. When the tables and the definitions are in two separate documents instead of one, should both documents have distinct names (e.g. registry definition report and registry data report), reserving the unqualified name for documents that hold both tables and definitions; or should one of the two continue to use the unqualified registry report name, with only the other one having a more specific name--and if so, which?

2. The part that holds the definitions needs to have a bunch of maturity levels, since there is a process for stabilizing them. The part that holds the data is less clear. Maybe that document has no maturity level of its own, and readers need to refer to the document holding the definitions to know whether a registry is a draft, finalized, obsolete, etc. Or maybe all the maturity levels that exist for the document that holds the definitions also exist for the document that holds the table, and they must be kept in sync. Or maybe the data-only document has a simplified set of maturity levels (e.g. Draft / Final / Discontinued).

The current text defines (variant 0):

• The term registry report and all the associated maturity levels apply to documents holding both definitions and tables as well as those holding definitions only.
• Documents holding tables only are registry data reports, and have no maturity level of their own. Readers should refer to the status of the document holding the registry definitions.

We could alternatively distinguish reports containing defintions but not tables from those containing both with something like (variant A):

A technical report that holds only registry definitions and no registry data is instead called registry definition report. The maturity levels of registry definition reports are the same as those described above for the combined registry report, except that the word “definition“ is included: Draft Registry Definition, Candidate Registry Definition, Candidate Registry Definition Snapshot, Candidate Registry Definition Draft, W3C Registry Definition, Obsolete Registry Definition, Superseded Registry Definition, Rescinded Registry Definition, Discontinued Registry Definition.

Independently, we could also give reports containing tables but not defintions statuses that match their definitions, like this (variant B1):

The maturity levels of a registry data report correspond to those of the technical report holding its registry definitions: Draft Registry Data, Candidate Registry Data, Candidate Registry Data Snapshot, Candidate Registry Data Draft, Proposed Registry Data, W3C Registry Data, Obsolete Registry Data, Superseded Registry Data, Rescinded Registry Data, Discontinued Registry Data.

Anytime there is a change to the maturity level of the technical report holding the registry definition, the Working Group must update and republish the registry data report to reflect this maturity change.

If we want reports containing tables but not defintions to have several maturity levels, but not quite that many, we could to something like this instead (variant B2):

The maturity levels of a registry data report are Draft Registry Data Report, Registry Data Report, and Discontinued Registry Data Report, with Registry Data Report corresponding to registry definitions in a W3C Registry (or W3C Recommendation), Discontinued Registry Data Report corresponding to registry definitions in an Obsolete, Superseded, Rescinded, or Discontinued technical reports, and Draft Registry Data Report corresponding to all registry definitions with any other levels of maturity.

Anytime there is a change to the maturity level of the technical report holding the registry definition, the Working Group must update and republish the registry data report to reflect this maturity change.

---

Note that because the combination registry report has to have maturity levels (because it contains the definition, which requires those levels), there would be a contradiction if we wanted the data-only report both to keep the unqualified registry report name and not have as many maturity levels.

[frivoal]

@dwsinger Having accepted the main PR for registries (#335), I suppose this issue is no longer relevant. Can we close it? I at least do no have any particular appetite to look into this aspect further.

[dwsinger]

Let's leave it open for the moment as people love to bikeshed names, and there are many good things you say here and it's only been open one day, so perhaps it will spark people's thoughts.

[cwilso]

I actually (for once!) am not here to bikeshed names :) - but I did want to chime in that the different titles are not quite as clearly and cleanly delineated in the text as one might desire. As I was reviewing how this would work with our legal team, it was somewhat concerning that the term "registry data" is sort of defined backward - the definition is given in the bullet list under "A registry has three associated components:", but the term is put at the end (unlike the definitions for terms like "registry", "registry table", and "registry entry"). Additionally, "Registry Data Report" is defined much after the other terms (well after it is used); and although "Registry Data Report" is capitalized, "registry report" and "registry" are not; it wasn't clear if that was intentional, or why. (I could understand why "registry section" might not be capitalized, but it seemed like the other terms should be consistent?)

I don't have an issue with any of the names; but it might be better organization to lay out the terms in one section, so a reader can understand how these terms fit together, and it could be clearer where the terms are being defined (For "registry data", I had to discern from the HTML source that that line was the DFN.)

[frivoal]

This issue was about picking which naming approach we should pick, and we picked one. I opened it, and consider it no longer relevant, so closing.
@cwilso, you point seems different: if I understand correctly, you're wondering about an editorial reordering to make things clearer. If you'd like to purse of that, could you open a separate issue?