Re: Proposal on PROV-DM reorganization

On 05/22/2012 02:16 AM, Graham Klyne wrote:
> With reference to your comments re. section 3 - I would be inclined
> to move it into the introduction section, but also to trim the
> explanation and rely more on the referenced prov-n document.  A
> brief description of the purpose of PROV-N, a link to the
> specification and maybe the examples should be enough, I think.

On 05/22/2012 06:09 AM, Graham Klyne wrote:
> On 22/05/2012 09:33, Luc Moreau wrote:
>> I had some push back to move this in section 1, since this document
>> is not about serialization.
>
> That's why I would trim it back.  The introduction covers topics
> such as document conventions, and it seems to me a reference to
> PROV-N is part of that.
>    As it's an external reference, a *small* amount of explanation
> might be appropriate.

You might add a statement at the end of section 1.2 Notational
Conventions:

   Examples throughout this document use the PROV-N Provenance
   Notation, briefly introduced in section XXX and specified fully in
   PROV-N [linked to doc].

I do like including the brief introduction of section 3, including the
very simple examples there.  I think most people won't even need to
get into PROV-N itself, and the few brief lines/examples here are
really enough for most people to get what it is all about, including
funky stuff like the ';' and '-'.

I kind of like it as a stand alone section, but you could move it into
the beginning of section 4 "Illustration of PROV-DM by an Example" if
you wanted (A new section 4.1 in front of the current 4.1).

On 05/22/2012 02:16 AM, Graham Klyne wrote:
> I (still) think the position of the example (section 4) between the
> overview (section 2) and the more detailed descriptions (section 5)
> breaks the flow of the reference material.  I think this is less of
> a problem than it was, as the first-time developer can switch from
> "sequential reading mode" to "reference mode"

I think you are right that it breaks things up, but I still support
the current flow over alternatives..

Curt

Received on Tuesday, 22 May 2012 12:57:56 UTC