High-level comments on Turtle document

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 :-/

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:”

Received on Friday, 25 May 2012 08:44:42 UTC