Re: Final CG report publication form is confusing

[Adding Jean-Gui so he knows I modified some templates.]

> On Dec 21, 2017, at 12:25 AM, Francois Daoust <fd@w3.org> wrote:
> 
> 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.

I have updated two resources:

 * New opening text on form that Chairs use to publish (see below)
 * The FAQ on publishing reports:
   https://www.w3.org/community/about/faq/#how-do-we-publish-a-specification
   

> 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”.

+1; I’ve adopted the “copy” language.

I hope this is an improvement. Note that I have not struck the word “publish” entirely, but tried to clarify what we mean by it.

> 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)

I’ve updated the FAQ (to refer explicitly to XML and RDF namespaces and link to "URIs for W3C Namespaces"):
 https://www.w3.org/community/about/faq/#can-i-use-w3c-namespaces-in-our-report

I hope that’s an improvement.

Thanks again and comments are very welcome,

Ian

=====
New opening text on form that Chairs use to publish

<p>On this page Chairs of the [Group Name] can publish either the first draft of a report or a final report. Here, "publish" means:

  <ul>
    <li>Register the report's URL with the Community Group system, and</li>
    <li>Announce its existence on the group's home page and on its mailing list.</li>
  </ul>

<p>A prerequisite for using this form is that there is a URL for the report. Publication does <strong>not</strong> mint a URL for a report, nor does it copy or otherwise modify a report at its current URL.</p>

<p>Before publishing, please review the <a class="none" href="/community/reports/reqs/">report requirements</a>. Learn more about <a href="/community/about/faq/#how-do-we-publish-a-specification">how to publish a group report</a>.</p>


--
Ian Jacobs <ij@w3.org>
https://www.w3.org/People/Jacobs/
Tel: +1 718 260 9447

Received on Monday, 8 January 2018 23:00:41 UTC