Re: High-level comments on Turtle document

* Richard Cyganiak <richard@cyganiak.de> [2012-05-25 09:44+0100]
> Gavin, Eric,
> 
> I feel bad about this message because you always seem to be just a few keystrokes away from going to LC, and always someone pops up with new complaints. Today it's my turn :-/

That's all right, at least we've got the Conformance section licked.

The fact that this document is getting a lot of attention hilights the degree to which the WG wants to use it not only as a standard which defines an explicit mapping from strings to RDF graphs, but also outreach material to help the world learn what is probably the most approachable interaction with RDF. While a minor PITA, that's also a Good Thing, with real benefit and growth to the community. In short, tx!


> So I have read the Turtle document with an eye on the overall structure, whether stuff is easy to find, and whether the normative/informative distinctions are made sensibly. I have a couple of concerns. Summary:
> 
>  • Everything is normatively defined twice
>  • Examples should be in the beginning, not halfway through
>  • Lots of tiny one-paragraph top-level sections bloat the TOC
>  • Conformance criteria (MUST etc) in informative sections
> 
> Some of this definitely falls under editorial discretion, and some under nitpicking, so by all means ignore anything you disagree strongly with. Details, section by section, follow below.
> 
> Best,
> Richard
> 
> 
> 
> > 1 Introduction
> 
> Ok. Perhaps break the example out into its own subsection 1.1?
> 
> > 2 Triples in Turtle
> > 3 RDF Terms in Turtle
> > 4 Collections in Turtle
> 
> I think it would help grouping them all under a single section, “Turtle Language Features” or so.
> 
> This allows reordering the subsections more freely to introduce features in a more natural order. For example, the predicate/object list examples are currently rather horrible due to long IRIs, and use literals which haven't been introduced yet at this point. Moving prefixed names and literals before predicate/object lists would help.
> 
> Also move the bit about Comments from the Introduction to a subsection in this Language Feature section.
> 
> I think that the entire section should be informative — everything said in it is said more explicitly and unambiguously in the Grammar and Parsing sections (or it could be made so by applying a tiny bit of extra rigor). This would remove potential normative contradictions, and would allow you to focus the Language Feature section purely on introducing the language, while the Grammar/Parsing sections spell out the detail.
> 
> > 5 Turtle Grammar
> > 6 Parsing
> 
> I'm not fond of having “5 Turtle Grammar” and then “5.4 Grammar”. I expect to actually get to the grammar when clicking the top-level “Grammar” link in the TOC; currently I still have to scroll around to find it. Perhaps rename 5 to “Formal Definitions”, and move the tiny sections “8 Identifiers for the Turtle Language” and “10 Media Type and Content Encoding” as subsections into it? Then make “5.4 Grammar” its own separate section, after “6 Parsing”?
> 
> > 7 Examples
> 
> Examples should be in the beginning of the document, *before* all the nitty-gritty details. Each example really illustrates a particular language feature, so perhaps break up this section, and move the individual examples into the respective early subsections?
> 
> > 8 Identifiers for the Turtle Language
> 
> Not worth its own top-level section. Make it a subsection, or fold it in with 10.
> 
> > 9 Conformance
> 
> I think it's good to make this the first normative section, because it explains how to read the rest of the document: What is normative and what isn't, what's the significance of the typographical conventions for MUST/SHOULD/MAY etc.
> 
> > 10 Media Type and Content Encoding
> 
> Not worth its own top-level section, especially since it's just a preview for an appendix. Make it a subsection.
> 
> > 11 Turtle in HTML
> 
> This is a really weird one.
> 
> If it's informative, then it cannot define anything new, so it can't have conformance criteria (MUST, MUST NOT), and cannot prescribe anything that's different from normal Turtle parsing.
> 
> If it's informative, then the section can merely provide some clarifications or examples that help understanding how the normative parts can be applied in a particular situation.
> 
> So something needs to be done here.
> 
> Perhaps rename the entire section to something slightly more descriptive, like “Embedding Turtle in HTML documents”? “Turtle in HTML” could mean absolutely anything.
> 
> The 11.2 section should be deleted IMO.
> 
> > 12 Turtle compared
> 
> 12.1 is pointless. Just make that a single sentence in the Introduction (with an actual link!): “Turtle's syntax is inspired by an earlier language Notation 3 [N3].”
> 
> 12.2 is pointless. If you really want to mention RDF/XML, add a sentence in the Introduction: “Turtle is a language for writing down RDF graphs, like RDF/XML [RDF-SYNTAX-GRAMMAR]. Unlike RDF/XML, Turtle is easy to read, easy to write by hand, and can serialize all RDF graphs.” I just wouldn't, to be honest.
> 
> 12.3 is great, and I'd like to see it given more prominence, because I assume that a good number of readers will get to Turtle after already being somewhat familiar with SPARQL. Perhaps even make it a subsection in the Introduction? “Turtle is the same language as the triple patterns in SPARQL, with the following differences:”

-- 
-ericP

Received on Friday, 25 May 2012 14:39:03 UTC