Best Practices review

Review comments on [1] as downloaded on 2013-12-04.

These are mostly editorial comments, some are more substantial but none 
fatal.

# Overall

The document is in much better shape that it was that last time I looked 
at it, well done! It does seem worth publishing as a working group note.

# Document structure

The section numbering is odd. I suspect all the sections are intended to 
be at the same level but currently it comes out with 99% of the document 
as subsections of section 1 then the short "Stability Properties" as 
section 2.

# Abstract

Reads oddly, three abstracts in one. Suggest just using the text of the 
later "Purpose of the document section" section.

If you retain the current text then:
   s/conventions through/conventions for/

# Scope

The reference on RDF is given as RDF-SCHEMA which doesn't seem 
appropriate, suggest using RDF Concepts.

# 1. Summary of Best practices

This section doesn't really line up that well with the things discussed 
in the document but on balance is probably better to have it than not 
have it, just.

## Box "NOMINATE A PILOT"

Suggest dropping. The linked section doesn't actually talk about 
nominating pilots and that's not always appropriate. People reading this 
document could be at many different stages in linked data publication 
experience.

## Box "SERIALIZATION"

"triplifaction" is not common terminology.

The title and content imply just serialization whereas presumably you 
mean data conversion as well.

Suggest:

"""
DATA CONVERSION Convert the sources data to a Linked Data 
representation. This will typically mean mapping the source data to a 
set of RDF statements about entities described by the data. These 
statements can then be serialized into a range of RDF serializations 
including Turtle, N-Triples, JSON-LD, (X)HTML with embedded RDFa and 
RDF/XML.
"""

## BOX DOMAIN

s/on authoritative/on an authoritative/

# 1.3 Vocabulary Discovery Checklist

This section seems weak but I can't think an easy way to improve it. I 
guess just leave it.

# 1.4 Using SKOS to Create a Controlled Vocabularly

Out of place, this should come later after at least 1.6 (Vocabulary 
Creation) and probably after 1.7 (Multilingual Vocabularies).

The box "It is a good practice to use SKOS in the following situations:" 
needs work. It mixes up indications when SKOS is appropriate (first 1-2 
bullets) with advice on how to do it (next 2-3 bullets) with something 
completely odd (last bullet).

Suggest:

"""
SKOS is appropriate in the following situations:

    * There is a need to publish a controlled list of terms or 
taxonomies having a special meaning for the domain.
    * The complexity and formality of an OWL ontology is not appropriate 
  (for example the terms are not themselves entities that will be richly 
described).

In creating a SKOS vocabulary bear the following good practice in mind:

    * Make a clear distinction between the collections of concepts 
(ConceptScheme) and the different individual concepts.
    * Define, when possible, a different namespace for each 
skos:ConceptScheme.
    * Structure the concepts in the list using properties 
skos:hasTopConcept, skos:broader, skos:narrower.
    * Consider defining a Class to represent all the skos:Concepts in 
your controlled list (this can facilitate declaration of properties that 
will use this list).
    * Provide multilingual labels for the terms.
"""

# 1.6 Vocabulary Creation

The box on versioning policy talks about a best practices section on 
Versioning that no longer exists, suggest dropping the last sentence.

# 1.7 Multilingual Vocabularies

s/represents the latest trend in/is an approach to/

[Not sure judgements like "latest trend" are appropriate here.]

s/ , , /, /

s/morphosintactic/morphosyntactic/

# 1.8 Best Practice for Choosing Entity URIs

The Q answer boxes are hard to read:
  - Some boxes use "Q/Y/N" others use "Q/A" suggest standardizing on the 
former
  - The nesting of questions in the second box in unclear, using braces, 
indenting or something to help people see which Q each N lines up with.

# 1.9 URI Design principles

The final section on TAG advice is hard to read for anyone doesn't 
already know all about this, needs some rewrite.

EXAMPLE 2 presumably shouldn't be called an "example", a Note? an advice 
box? Also drop the pre formatting, it doesn't print properly.

Either drop the term http-range-14 or put that up front and explain it.

# 1.11 IRIS

s/homegenic/uniformly/

# 1.13 Security and Hosting

This whole section seems very related to the US Government specific 
process. It is not clear to me that it says anything specific enough to 
be useful in a non-US context.

Suggest dropping most of the section and replace by a simpler statement 
to the effect that "that for specific data and organizations there may 
be particular security considerations, so involve appropriate advisors 
early on in the process. Detailed considerations of security issues are 
beyond the scope of this document"

Dave

[1] https://dvcs.w3.org/hg/gld/raw-file/default/bp/index.html

Received on Wednesday, 4 December 2013 17:34:59 UTC