Re: Preparing editor's drafts -- Q's for the team contacts

Hi Richard,

thanks for kicking this off, we have to go through these steps indeed...

On May 25, 2011, at 24:50 , Richard Cyganiak wrote:

> A bunch of questions for the team contacts.

Much of these questions are, actually, to be answered by WG decisions and not by Sandro or I... 

> 
> We have resolved the first issues that imply spec changes, and the chairs are urging the RDF Concepts editors to prepare a presentable editor's draft. So it is urgent that the support infrastructure for editors is put in place. There are also some basic questions that all editors will face as soon as they convert their document to ReSpec.

Exactly...

> 
> Here we go:
> 
> 
> 1. I assume there will be a joint Mercurial repository for the WG. Where is it? I can keep my work under version control in a local repository for now, but I'd like to start collaborating with my co-editor rather sooner than later.

I think setting up such a repository asap is good. Note that I have never used mercurial before, so we will have to learn as we go (unless Sandro or Eric have already used it...)

The current set of archives for various other working groups are at:

http://dvcs.w3.org/hg

we have to define what the name of our archive is (I guess 'rdf' is the obvious answer), and who the 'contact' persons are (I guess Sandro and I at the minimum, it may be wise to add somebody else; this will become a big archive). Once we have these decisions, we can put in a request to the system team:

[[[
• Requesting a Mercurial repository. Email sysreq@w3.org with the following information:
   • name for the repository (see examples)
   • contact for this repository
   • groups that are allowed to push changes to this repository (one or more DBWG groups; additional groups may be added later)
]]]

I guess the obvious answer to the last question is to allow for only our group to edit. Our DBWG id is 46168


> 
> 2. I assume we will do public editor's drafts. What will the IRI of the RDF Concepts draft be?

I am not sure which URI you are asking, but I presume you ask for the final IRI of each our documents. That is, actually, an important decision this group has to take. Indeed, there are two possibilities:

1. We aim at a set of documents that fully and absolutely supersede the old documents. This means we'd continue to use the http://www.w3.org/TR/rdf-concepts/ for what we call the 'short URI' in our document management jargon with, of course, the 'dated URI-s' reflecting the current date. This means that, in future, if somebody uses the short uri as a reference, he/she will fall on the new version of the document. Note that this may lead to some disruptions during the development process when users will suddenly find themselves reading working drafts. As an example, this is what the xml guys did: the http://www.w3.org/TR/xml/ URI leads to the latest (5th edition as of today) of XML.

2. We decide to start with a clean plate. In this case we will have to decide what the 'short URI' or, more exactly, what the 'short name' is (ie, what replaces 'rdf-concepts'). This is definitely a WG decision. This is the route taken by the OWL and the SPARQL working groups (eg, http://www.w3.org/TR/sparql11-query/ as opposed to http://www.w3.org/TR/rdf-sparql-query/).

I guess it may be possible to use a short name for the development time and change this on the last minute to switch to the old names but I would not favour that, personally; it may become messy on long run. Note also, that it should be possible, if we go for an RDF 1.1 route, to have a note added to the old RDF document making it 'editorially' obsolete when we publish our recs, see, for example,

http://www.w3.org/TR/owl-guide/

_Personally_ I would go for RDF 1.1 with option #2. But that is my personal choice, with my staff contact or activity lead hat off...


> 
> 3. Old title: “Resource Description Framework (RDF): Concepts and Abstract Syntax”. Is this now “RDF Concepts and Abstract Syntax (Second Edition)” or “RDF 1.1 Concepts and Abstract Syntax” or something else? What shall I use as a working title?

This is, in fact, the same issue as the one before. If we adopt a numbering (like the SPARQL and OWL have done), then we would probably use a different short name. If we just go for a 'second edition' then the XML approach might be the winning one.

> 
> 4. I believe it is W3C policy to add the names of additional editors to the list of editor names from previous editions that are already in the spec. Affiliations and contact details of the previous editors may have changed; should an effort be made to contact them and get those details fixed?
> 
> 5. The specs have a “Series Editor” (Brian McBride). I believe that ReSpec doesn't have such a feature. How to handle this?

Let me answer these two questions in one step.

The only W3C policy is that there are editors that have to be listed, and that is it. All other entries like 'previous editors', 'authors', 'series editors', etc, are defined and used by working groups and, I am afraid, there is no real consistency there. All I can give you is some examples.

- The SPARQL WG has indeed decided to refer to the previous editors under a separate heading (wherever appropriate).  
- For RDFa the old editors were just listed, and possibly new ones added
- OWL 2 started fresh and there is no reference to previous editors
- the old RDF series is the only one where I saw a 'series editor'...

(B.t.w., it is probably wise to seek out the new affiliation for the previous editors.)

Additionally, there is also an issue on whom else to add to the cover page. 

- The RDFa document bear a separate entry called 'authors', listing those who have really contributed to the content but were not editors of the text proper
- The OWL 2 document have a similar entry called 'contributors'.

I am more in favour of the 'authors' in this respect, for a very down-to-Earth reason: some of us, in the academic world, have to add to our own publication lists. If one's name appears as author, I do not think it is a problem adding that to one's official publication list; the term 'contributor' may raise some eyebrows among academic bean counters, so to say...

While we are at it: lately all (Semantic Web, possibly others, too) groups have taken the habit of adding a separate acknowledgement section at the end listing the active members of the working group. I think we should adopt that, too. (A typical case where an external file should be used in RecSpec...)

> 
> 6. ReSpec wants to know a URI for the patent status of the WG. From the config file:
> 
>  // URI of the patent status for this WG, for Rec-track documents
>  // !!!! IMPORTANT !!!!
>  // This is important for Rec-track documents, do not copy a patent URI from a random
>  // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
>  // Team Contact.

wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/46168/status",

B.t.w.: I would think that looking at the source of the RDFa 1.1 Core document might be helpful:

http://www.w3.org/2010/02/rdfa/sources/rdfa-core/Overview-src.html

Shane McCarron has added a number of additional tricks for cross references, formatting of examples, etc, that use the extension mechanism of recspec (eg, formatting examples without the necessity to use those ugly < and > forms, stuff like that).


> 
> 7. Am I right to assume that the metadata.rdf thingy in the footer of the documents is obsoleted by ReSpec's RDFa output?

I would think so indeed.

> 
> 8. Do we have a policy regarding the use of RFC 2119? I note that RDF Concepts contains one uppercase SHOULD, but does not make reference to RFC 2119. If we wish to use it in a document, is there boilerplate for defining the magic words?

I do not think there is a strict policy, but I think it is wise to add a reference somewhere. Here is the very simple comformance section from RDF 1.1 core:

[[[
4. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
]]]

which I think is worth having as a boilerplate. But the group may decide otherwise.

I hope these help...

Ivan


> 
> Best,
> Richard


----
Ivan Herman, W3C Semantic Web Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
PGP Key: http://www.ivan-herman.net/pgpkey.html
FOAF: http://www.ivan-herman.net/foaf.rdf

Received on Wednesday, 25 May 2011 08:35:11 UTC