schema: Update comments

Change-Id: I4b8ea3d09f75bf14d87a1c3f1d661edaa0d6d162

1 files changed, 23 insertions, 12 deletions

diff --git a/schema/baserock-example.schema b/schema/baserock-example.schema
index 1f90a891..8a0658de 100644
--- a/schema/baserock-example.schema
+++ b/schema/baserock-example.schema
@@ -1,14 +1,16 @@
 # Baserock Definitions schema example
 
-# This ontology teases out a simple formal model of the data represention
-# aspect of the Baserock definitions format (v5).
+# This is an attempt to describe the data model part of Baserock definitions
+# format.
 #
-# It's not a great example of an ontology, because it models a generic problem
-# using terms and a data model tied closely to how a couple of specific tools
-# work. In future we need to produce a more general-purpose model. I hope
-# this schema is a useful step towards doing that.
-
-# This is an RDF + OWL ontology represented as RDF/Turtle data.
+# See also: http://wiki.baserock.org/definitions/current/
+#
+# This is not a brilliant schema, in Linked Data terms, because it's using
+# Baserock-specific terminology and a rigid layout, instead of being a generic
+# vocabulary for describing how to assemble software. However, it maps closely
+# to existing data (the Baserock reference systems).
+#
+# This is an OWL ontology represented as RDF/Turtle data.
 
 # NOTE: I absolutely HATE CamelCase but it seems to be the convention for RDF
 # property names. I'm undecided on whether it's worse to condemning everyone
@@ -16,19 +18,27 @@
 # inconsistent with the rest of the Linked Data world.
 
 # Things you can do with this:
-
-# Check it is valid:
+#
+# Check it is syntactically valid:
 #  rapper -i turtle baserock-example.schema
 #
 # Visualise it in a rubbish way:
 #  rapper -i turtle -o dot baserock-example.schema | dot -Tpng > schema.png
 #
+# Rapper is part of the 'raptor2' package on most distros.
+# See: http://librdf.org/
+#
 # Edit with Protégé:
 #  just open it in protege, it can save to Turtle format as well but will lose
 #  comments and formatting.
 #
+# Protégé is a Java application for editing OWL ontologies. I prefer to edit
+# them as Turtle text files but maybe you like compex GUIs.
+# See: http://protege.stanford.edu/products.php#desktop-protege
+#
 # Browse it using the example browser program.
 #   See: browser/README.txt
+#
 
 
 # Metadata
@@ -91,9 +101,10 @@
 
 ## Shared properties
 
-# 'name' is converted to a URL at load time.
+# 'name' becomes part of the URL when we import definition .morph files as RDF,
+# so it doesn't need a property.
 
-# use dc:description for 'description', see:
+# Use dc:description for 'description', see:
 # http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-description