W3C home > Mailing lists > Public > public-gld-wg@w3.org > May 2013

Re: ADMS review

From: Phil Archer <phila@w3.org>
Date: Fri, 03 May 2013 08:48:11 +0100
Message-ID: <51836BBB.2010607@w3.org>
To: James McKinney <james@opennorth.ca>
CC: W3C public GLD WG WG <public-gld-wg@w3.org>, Makx Dekkers <makx@makxdekkers.com>
Thanks very much James, pls see below.

On 03/05/2013 03:51, James McKinney wrote:
> Hi Phil,
> Answers inline. In general, I am happy with all the changes.



>>> 2. I am unable to parse "A level as defined in a list such the European Interoperability Framework [[EIF2]] for which an Asset is relevant." Similarly, "The interoperability level for which the Semantic Asset is relevant."
>> The EIF document defines a set of interoperability levels - Legal, Organisational, Political etc. - and the idea is that you can declare which of those levels an asset is at. See https://joinup.ec.europa.eu/svn/adms/ADMS_v1.00/ADMS_SKOS_v1.00.rdf for a bunch of SKOS concepts that include these.
>> If you can suggest better wording I'm happy to use it.
> How about "The interoperability level (e.g. legal, organizational, political, etc.) of the asset. The interoperability level may be taken from a list of levels, such as that of the European Interoperability Framework [[EIF2]]." I'm still fuzzy about what an interoperability level is, but this is a bit more clear to me.

Thank you - I have now updated the doc to use this exact wording

>>> 3. Why do we not include classes in the "Properties and Relationships" section (which should be renamed "Vocabulary Reference" if we add classes)?
>> I don't think it's unusual to list classes separately from properties (FOAF and DC both do it). We need to give slightly different info about classes than properties. But I have added to the text for each one indicating the property that links to it.
> I'm not sure what added text you are referring to. Could you point one example out for me?

Yes. For all the classes I've now added text to  say which properties 
link to it. for example, the full text for the interoperability level says:

The interoperability level (e.g. legal, organizational, political etc.) 
of the Semantic Asset, linked using adms:interoperabilityLevel. The 
interoperability level may be taken from a list of levels such as that 
of the European Interoperability Framework [EIF2].

The addition of "linked using adms:interoperabilityLevel." was an 
attempt to answer your point. It means that the object type properties 
(relationships) are all cited in the info about the classes although the 
datatype properties are only mentioned in the listing.

>>> 3. I'd appreciate an index at the beginning of the Properties and Relationships section. It's also hard to determine what properties go with which classes. Could we group properties under the class they are related to for easier reading, as is done in DCAT? For properties that can be used on many classes, like dcterms:description, we can add those in a catch-all subsection, or repeat them in each subsection.
>> As well as the above, I've slightly changed the markup so that classes are listed in the ToC. All properties are listed there (in alphabetical order). I hope that's sufficient listing?
> Does the ToC not appear in the raw file at https://dvcs.w3.org/hg/gld/raw-file/default/adms/index.html ? The ToC as you describe it sounds sufficient.

This worries me :-( The ToC is generated by re-spec, the JavaScript 
library that Robin Berjon created, that puts in all the boiler plate 
stuff, handles the references and so on. Hmmm... you don't see that 
which means there's something wrong.

I use Opera - check, it works.
Try Firefox - check, it works.
Try IE - check, it works.
Try Safari - check, it works.

Ah... you're a Chrome user I see.

Any other browser will show you the formatted page. Dunno if there's 
something I'm supposed to do to make it work in Chrome but before it 
goes to actual publication we generate a static HTML doc so the problem 
won't occur at that stage. (It's probably a cross origin thing. The 
re-spec library is on dev.w3.org, the Mercurial repo is on dvcs.w3.org).


>>> 10. representationTechnique seems to be an unusual term to describe "The machine-readable language in which a Distribution is expressed. This is more fine-grained than file format, for example 'Word 2003'". I don't have a better suggestion, though.
>> I agree it is a little odd but that's the term that was minted and that is now in use (@Makx - correct me if I;m wrong but joinup uses it?)
> If it's in use, then we can leave it as-is. Otherwise, I had proposed "It seems to me that representationTechnique acts as a note to dcterms:format. In that case, maybe 'formatNote' would be better than 'representationTechnique."

Makx has confirmed that it is indeed in use so I'd like to leave it 
alone if poss.

Do let me know if there's more I need to look at.



>>> On 2013-04-07, at 4:43 PM, James McKinney wrote:
>>>> Here's a first review that doesn't go into the domain model.
>>>> 1. Small fixes:
>>>> * xml -> XML
>>>> * data set -> dataset
>>>> * anad -> and
>>>> * 'a document' -> a document (without quotes)
>>>> * Semantic Interoperability -> Semantic interoperability (lowercase "i")
>>>> * consuption -> consumption
>>>> * a few missing periods at the ends of paragraphs
>>>> 2. I find the document's first sentence to be a much clearer description of semantic assets than the introduction's first sentence. Can we simply re-use the clearer sentence?
>>>> 3. Most of the introduction is actually about explaining why we have ADMS when we already have DCAT. Perhaps this can be moved to a new "Rationale" section, maybe as a subsection of "Vocabulary Overview"?
>>>> 4. Add an "Acknowledgements" header for the three "The original development of ADMS ...", "ADMS was first developed by PwC EU Services ...", and "This version of ADMS ..." paragraphs, and perhaps move it to the end of the document, like in ORG.
>>>> 5. Add a "Conformance" header before "A data interchange, however that interchange occurs, ..." and move this section before Namespaces.
>>>> 6. It's unusual that the terms described in the Terminology section are never used elsewhere, i.e. "Semantic interoperability" and "Semantic interoperability asset". We use "semantic asset" everywhere, which is defined in the introduction, but it is never said whether it is a synonym of "semantic interoperability asset". Do we need this section?
>>>> 7. If the above changes are made, the Introduction will be very short. I would move the "Vocabulary Overview" into the introduction (it makes sense to do an overview as early as possible in the document). Here's a possible table of contents, in which I also move "Namespaces" down, closer to the reference "Properties and Relationships" section:
>>>> 1. Abstract
>>>> 2. Vocabulary Overview
>>>> 2.1. Terminology
>>>> 2.2. Rationale
>>>> 2.3. Example
>>>> 3. ADMS Domain Model
>>>> 3.1. Primary Concepts
>>>> 3.2. Secondary Concepts
>>>> 4. Conformance
>>>> 5. Namespaces
>>>> 6. Properties and Relationships
>>>> 7. Acknowledgements
>>>> James
>> --
>> Phil Archer
>> http://philarcher.org/
>> +44 (0)7887 767755
>> @philarcher1


Phil Archer
W3C eGovernment

+44 (0)7887 767755
Received on Friday, 3 May 2013 07:48:38 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:52:08 UTC