Re: How best to indicate a Registry section in a Rec track document?

Thanks Jeffrey, for the in depth response. Comments inline preceded by [NM]:

From: Jeffrey Yasskin <jyasskin@google.com>
Date: Tuesday, 7 November 2023 at 20:33
To: Nigel Megitt <nigel.megitt@bbc.co.uk>
Cc: "spec-prod@w3.org" <spec-prod@w3.org>
Subject: Re: How best to indicate a Registry section in a Rec track document?

I don't have strong opinions here, but some thoughts:
·         https://github.com/w3c/tr-design/issues/283 asked for some sample registry tables in tr-design. The fact that you've added CSS to support your registry is, I think, an indication that tr-design should have an opinion on what these sections look like.
[NM] +1
·         I think I agree that a REC's SotD should mention any included registries, since they're parts of the document that haven't been endorsed by the AC, that can be republished without the WG's involvement, that aren't covered by the patent policy<https://www.w3.org/2023/Process-20231103/#reg-pub>, etc. Probably any Patent Review Drafts<https://www.w3.org/2023/Process-20231103/#patent-review-drafts> should also mention the registries, because of the difference in patent policy. I'm less sure that any earlier stages need to call out the registries, since I don't think they'd get updated with any weaker change control than the rest of the document ... but it might still be a good idea to foreshadow the later stages' section about them.
[NM] As it happens we had already signposted the need for registries when the Call for Exclusions went out, but had not added the registry definitions or tables at that stage. I’m not sure if more detail will be needed when we transition to CR.
·         In the SotD, I think it'd be ideal to link to the particular registries inside the document. That implies that the spec's metadata should list registry IDs for the SotD to include ... which is a decent hook to trigger the inclusion of the registry boilerplate.
[NM] I’d rather the SOTD didn’t have to mention each specific registry, because that makes it more complex to add boilerplate text into that section; I think it should be enough to indicate that the report contains at least one registry table. This is in the context of a Rec track document specifically. I can see that in case other documents want to reference a registry table, it could be helpful for tooling later if each published registry table were uniquely identified.
·         The Process's discussion of "a registry section"<https://www.w3.org/2023/Process-20231103/#reg-pub> is in a sentence with a plural subject and a singular indirect object, so it's not clear whether the whole document gets one registry section or each registry gets its own section. But you're suggesting putting an individual registry into two different parts of the document, which doesn't follow either interpretation. :) But then, the "registry"<https://www.w3.org/2023/Process-20231103/#registries> is defined as having 3 components: the definition, the tables, and the referencing specifications, and clearly the referencing specifications aren't going to be inside the registry section. Also, the Process says "A ... registry section is purely documentational" but also "Defining a registry requires wide review and consensus", which isn't really compatible with the registry definition going into the registry section. So I think there's a Process bug here, and we should figure out the right thing to do and make the Process match that, rather than trying to conform exactly to the existing Process.
[NM] +1. At the moment it doesn’t seem to say anything about the update requirements for the Registry Definition itself. At the moment the wording “is purely documentational” seems to apply to the Registry Definition, and that feels wrong – why bother requiring specific rules about changing Registry Tables if the text that defines those rules can be changed without any process?
·         I'm nervous about putting the registry tables next to the part of the spec that calls them, because the change control is so different. Your "registry section" box could work as a way to identify that difference, and I agree that it makes the spec easier to use. Maybe we should have Respec and Bikeshed automatically include particular boilerplate next to registry tables that also calls out the difference in change control and links to the associated registry definition?
[NM] I’d be happy with that.
o    The tables and their definitions should cross-link to each other.
[NM] I agree, and already did that in https://github.com/w3c/dapt/pull/196

·         I think <figure> might be the right markup to surround registry tables?
[NM] I guess that could work. I don’t have strong opinions, and I’m not sure how assistive tech deals with a <table> inside a <figure> as distinct from a <table> on its own. The other question this raises for me is: should all Registry Table sections be marked as informative/non-normative?
·         I wouldn't put the registry section in an appendix, and I'd title it something like "Registry Definitions" rather than "Registry Section". This should roughly imitate the ways the IETF uses "IANA Considerations" sections to define their registries. https://www.rfc-editor.org/rfc/rfc8615.html#section-5 has a simple one.

[NM] I called it that because of the Process wording in §6.5.2<https://www.w3.org/2023/Process-20231103/#reg-pub>:

“The registry report<https://www.w3.org/2023/Process-20231103/#registry-report> or registry section<https://www.w3.org/2023/Process-20231103/#registry-section> must:

  *   Clearly label the registry report<https://www.w3.org/2023/Process-20231103/#registry-report>/section<https://www.w3.org/2023/Process-20231103/#registry-section>, its tables<https://www.w3.org/2023/Process-20231103/#registry-table>, and its registry definitions<https://www.w3.org/2023/Process-20231103/#registry-definition> as such”
[NM] It seemed like the easiest way to meet this requirement was to call the section “Registry section” and within it include the “Registry Definition”.
·         You have a "registry tables" section<https://pr-preview.s3.amazonaws.com/w3c/dapt/pull/196.html#registry-table>, but I think the things inside it are parts of the registry definition rather than the registry tables.
[NM] I will rename it “Registry Table Definitions”.
HTH,
[NM] It really does, thanks again.

Nigel

Jeffrey

On Mon, Nov 6, 2023 at 2:38 AM Nigel Megitt <nigel.megitt@bbc.co.uk<mailto:nigel.megitt@bbc.co.uk>> wrote:
Has there been any work on specific text or formatting for indicating sections of Rec track documents that are Registry Sections, as per https://www.w3.org/2023/Process-20231103/#reg-pub ? Not sure if this is a question for the ProcessCG, but it feels like an editing question initially.

In particular, things that occurred to me while preparing https://github.com/w3c/dapt/pull/196 :

· It seems like a good idea to mention in the SOTD that the document contains a Registry Section – I wrote my own additional text, but maybe it would be better to have common wording, and an additional value in Respec’s config specStatus value to support the conditional inclusion of that wording.

· The Process wording seems to allow for a single Registry Section, but structurally, it would be better to put the Registry Tables inline in the document in the place where they appear. I’m going to assume that it’s okay to do that, but when doing so, it would be a service to the reader if there were some indication that the table is subject to change outside the normal Rec track update process. Hence this email!

· (maybe a Respec question) Sometimes it’s helpful to insert into the document values that derive from the Respec config, but it isn’t straightforward to do that. I created a clunky post-processing function for Respec to replace values in elements with specific class names, but it’s ugly. In this case I wanted to put in to the Registry Definition that the mechanism for asking for a change is to raise an issue on the version control system (aka repository), and link to it. The URL for the GitHub repo is information that Respec knows, so I wanted to insert that as a value into href attributes wherever they appeared.


Any suggestions appreciated!

Nigel