search

w3c / controller-document

Controller Documents
https://w3c.github.io/controller-document/
Other
5 stars 3 forks source link

Make Conformance Classes a top-level section #7

Open selfissued opened 2 months ago

selfissued commented 2 months ago

Conformance Classes currently appears as a subsection in the Introduction section. That seems far too early in the document for readers to have any context to be able to understand it.

I suggest moving it to its own top-level section late in the document, as was done in VC-JOSE-COSE.

iherman commented 1 month ago

The issue was discussed in a meeting on 2024-05-15

View the transcript #### 3.2. Make Conformance Classes a top-level section (issue vc-controller-document#7) _See github issue [vc-controller-document#7](https://github.com/w3c/vc-controller-document/issues/7)._ **Manu Sporny:** We've had this discussion before. … That's why the conformance section is where it is. … We can move it to a top-level section. … I'm -1 to moving it later in the spec. … We do refer to it early in the specification. **Michael Jones:** as Manu said the things to conform to need reference at the front of the document. Should have statements of conformance before you are conforming to it. **Ivan Herman:** My real concern is consistency. … We have a family of recommendations. … I didn't realize that jose-cose was inconsistent. **Michael Jones:** it's not that it's inconsistent. **Manu Sporny:** I think it's fine to define a concept and then elaborate on it later on.
iherman commented 2 weeks ago

The issue was discussed in a meeting on 2024-06-19

View the transcript #### 3.6. Make Conformance Classes a top-level section (issue controller-document#7) _See github issue [controller-document#7](https://github.com/w3c/controller-document/issues/7)._ **Brent Zundel:** On to 7. … Conformance classes appears too early in the document. Move to late in the document. … We had a conversation about this last month. JOSE-COSE is the only document that does it this way, controller document more closely aligns with other documents produced. No agreement that this should be done. … We don't have consensus that this issue should be addressed. **Manu Sporny:** Objects to moving this to somewhere else. In ReSpec, conformance section has boilerplate and top has "How to read this document". … Standard boilerplate goes at the top of every W3C specification. Good for people to read that bit. … Moving in document doesn't appear to make it better than what we have right now. … Have this setup in multiple specifications, no object until now. **Brent Zundel:** On to 18.
msporny commented 1 week ago

The group has discussed this twice and there is no support to make the conformance section a top level section. Our specifications have contained conformance sections in the introductory portion of the specifications for years now and there does not seem to be a desire to change that. Marking as pending close.

selfissued commented 6 days ago

VC-JOSE-COSE has this as a top-level section, so there's precedent in the WG for doing it this way. It's more logical and reads more easily, since you're not giving the reader information before they have the context to understand it.