Final CG report publication form is confusing

Hello there,

The Web Media API Community Group just published a final report of the Web Media API Snapshot 2017 specification. Exchanging with Mark Vickers, CG chair, while preparing that publication, we noted that the instructions on the publication form are somewhat misleading:

1. The description of the "URI of Final Specification" does point out that the report must be published on w3.org, but the existing text makes it sound as if our system will just handle the actual publication itself, and copy the latest version of the draft report somewhere on w3.org. The FAQ is not any clearer. The text should clearly say that the actual publication is a prerequisite to filling out this form, and should provide some guidance for how this can be done (be it only with a "get in touch with your nearest W3C team contact", which may be enough given that most CGs that publish final reports somehow have a connection with someone on the team. Sending an email to site-comments@w3.org could be an option too). That first step will give the URI to enter in the form.


2. The use of the term "publishing" is ambiguous. It can mean "copying the doc to a location" and "filling out the form". Typically, the term is used with both meanings in the description:
 - "Final Reports must be *published* on the W3C web site" (copying the doc)
 - "Learn more about how to *publish* a report" (filling out the form)
The former term could perhaps be replaced by "copying". The latter term could perhaps be replaced by "announcing".


3. Looking at the FAQ for possible instructions on how to get a URI on the w3.org domain name, one will bump into "Can I use W3C namespaces in our Specification?":
https://www.w3.org/community/about/faq/#can-i-use-w3c-namespaces-in-our-report

This entry states that the URI https://www.w3.org/ns/[shortname] may be used. That will only add to the confusion:
- the notion of namespace can be somewhat foreign to "API people"
- as such, it reads like an invitation to use that URI for the final report, which is not what we want.

The notion of namespaces could perhaps be clarified by linking to the Namespaces in XML spec that defines what we mean by namespaces, as done in our URIs for W3C Namespaces policy for W3C Technical Reports:
 https://www.w3.org/2005/07/13-nsuri
(although the dependency on "XML" feels a bit outdated nowadays)

Thanks,
Francois.

Received on Thursday, 21 December 2017 06:25:40 UTC