Re: Your feedback on pre-LC prov-o

Tim,

By "term description" I mean an ontology term description in the document (class or property description).

Yes, this us about being able to cross-reference easily, to quickly find the description of a particular term.

When I use specifications as a developer/designer, I very frequently use the ToC to locate a particular item or topic of interest, and go straight to that section. I do this when looking for a specific piece of information, when the *last* thing I want to do is read through the document. It's similar to using the index in a text book. I find this is my dominant mode of actually *using* standard specifications - even ones I'm very familiar with - there's too much to remember all the details (across multiple standards that must be used in concert). And often the details only make sense or matter in the context of creating a particular application, when I want an answer to a specific question, not a tutorial on the meaning of (life, whatever).

I think the structure of PROV-O works pretty well for this mode of use when reading online hypermedia, but that use isn't supported by the printed presentation. Ironically, I think the compactness you seek only really matters when the document is printed.

My suggestion would be to leave the summary tables as they are, give each if the class/property descriptions a section number, and include them in the table of contents at the front of the document. That way you keep your compact presentation in the document body for readers (which *is* a good thing imo, and I wouldn't want to lose), but also provide navigability for on-paper readers.

#g.

-- 
Sent from my Android phone with K-9 Mail. Please excuse my brevity.

Timothy Lebo <lebot@rpi.edu> wrote:

Graham,

Thanks for your patience with this issue.
I'm still trying to figure out the nature of the problem, so we can work out a reasonable solution.

On Jul 19, 2012, at 6:05 AM, Graham Klyne wrote:

> Tim,
> 
> You asked:
> > Is the problem you have with granularity? You want to know *which page* it is on?
> > These narratives are very small, and I find it hard to believe that a quick scan of the section wouldn't get you there.
> 
> Granularity is a big part of it, but also the section references you mention are buried in text which makes them harder to spot.


The majority of my reaction to this is that one should read (it's but a few sentences), 
but I appreciate that many readers will be trying to orient and will be searching for something else.

Would putting the "Section 3.1" before "Starting Point classes and properties" [1] help?
[1] http://aquarius.tw.rpi.edu/prov-wg/prov-o#prov-o-at-a-glance


> Also, section numbering of the term descriptions would help (in conjunction with a ToC).

I'm not sure I understand what this is. "term descriptions"?
I'm starting to think that a table like [2] is what you're looking for, but with explicit section labels in the cells.

If I replaced the current listing in [1] with a table like this, it would have a lot of redundancy (only 3 distinct values in the "go to" column).
All of that b/c we want to avoid reading a few sentences?

[2] http://dvcs.w3.org/hg/prov/raw-file/default/model/prov-dm.html#prov-dm-types-and-relations


> 
> FWIW, section 4.1 covers 6 pages in my printed copy, with quite small text - that's quite a bit to flip through when trying to find a particular property.

Okay, so the cross reference is your concern? This is very different from the narrative section.
You have concerns about both sections, or just the cross reference section?
Or, has your request grown?

> The total of material for which I'd like to see a more detailed ToC is 47 pages.
> The trouble is, I suppose, is that there isn't really a way to create an index that works on paper without it occupying a whole page. 

I *might* be able to number each cross reference entry. Then, we'd have a table that says: prov:Activity = 1, prov:Agent = 2, etc.

If you're printed, then if you're on page 32 you'll see that you're at "entry 89" and you need to back up to get to "entry 67".

Would that work?

Regards,
Tim



> For making a printed version navigable, I think that's a price worth paying, but YMMV.
> 
> #g
> --
> 
> On 18/07/2012 14:27, Timothy Lebo wrote:
>> Graham,
>> 
>> In http://aquarius.tw.rpi.edu/prov-wg/prov-o#prov-o-at-a-glance :
>> 
>> we say that "these classes and properties are described in section 3.1"
>> 
>> prov:Activity
>> prov:Agent
>> prov:Entity
>> prov:actedOnBehalfOf
>> prov:endedAtTime
>> prov:startedAtTime
>> prov:used
>> prov:wasAssociatedWith
>> prov:wasAttributedTo
>> prov:wasDerivedFrom
>> prov:wasGeneratedBy
>> prov:wasInformedBy
>> 
>> and "these classes and properties are described in section 3.2"
>> 
>> prov:Bundle
>> prov:Collection
>> prov:EmptyCollection
>> prov:Location
>> prov:Organization
>> prov:Person
>> prov:SoftwareAgent
>> prov:alternateOf
>> prov:asInBundle
>> prov:atLocation
>> prov:generated
>> prov:generatedAtTime
>> prov:hadMember
>> prov:hadPrimarySource
>> prov:influenced
>> prov:invalidated
>> prov:invalidatedAtTime
>> prov:mentionOf
>> prov:specializationOf
>> prov:value
>> prov:wasEndedBy
>> prov:wasInvalidatedBy
>> prov:wasQuotedFrom
>> prov:wasRevisionOf
>> prov:wasStartedBy
>> and "these classes and properties are described in section 3.3"
>> 
>> prov:ActivityInfluence
>> prov:AgentInfluence
>> prov:Association
>> prov:Attribution
>> prov:Communication
>> prov:Delegation
>> prov:Derivation
>> prov:End
>> prov:EntityInfluence
>> prov:Generation
>> prov:Influence
>> prov:InstantaneousEvent
>> prov:Invalidation
>> prov:Plan
>> prov:Quotation
>> prov:Revision
>> prov:Role
>> prov:Source
>> prov:Start
>> prov:Usage
>> prov:activity
>> prov:agent
>> prov:atTime
>> prov:entity
>> prov:hadActivity
>> prov:hadGeneration
>> prov:hadPlan
>> prov:hadRole
>> prov:hadUsage
>> prov:influencer
>> prov:qualifiedAssociation
>> prov:qualifiedAttribution
>> prov:qualifiedCommunication
>> prov:qualifiedDelegation
>> prov:qualifiedDerivation
>> prov:qualifiedEnd
>> prov:qualifiedGeneration
>> prov:qualifiedInfluence
>> prov:qualifiedInvalidation
>> prov:qualifiedQuotation
>> prov:qualifiedRevision
>> prov:qualifiedSource
>> prov:qualifiedStart
>> prov:qualifiedUsage
>> prov:wasInfluencedBy
>> 
>> Is the problem you have with granularity? You want to know *which page* it is on?
>> These narratives are very small, and I find it hard to believe that a quick scan of the section wouldn't get you there.
>> 
>> Thanks,
>> Tim
>> 
>> 
>> 
>> On Jul 18, 2012, at 4:33 AM, Graham Klyne wrote:
>> 
>>> Tim,
>>> 
>>> I just checked this:
>>> [[
>>> (1) would it be possible for term names to be included in the table of contents? I found some aspects the document could be difficult to navigate/cross-reference in printed form.
>>> 
>>> PENDING-REVIEW EDITORIAL http://aquarius.tw.rpi.edu/prov-wg/prov-o#prov-o-at-a-glance should be the "print-friendly index" that you're looking for. It is at the top of the document.
>>> ]]
>>> 
>>> Unfortunately, this doesn't really help, as there's no obvious ordering of the terms. (Ideally, they would be page-numbered, but I recognize that HTML isn't very good for that kind of thing (I'm surprised that after all these years, HTML still doesn't support ToC generation as standard). The compromise I usually make is to have a table of contents that matches the document layout, with section numbering, so I can use that as a kind of "map". That you don't section-number the individual term descriptions is part of my problem.)
>>> 
>>> This is just an editorial issue, and rather depends how much you care about usability of the spec in print form.
>>> 
>>> #g
>>> --
>>> 
>>> On 17/07/2012 18:45, Timothy Lebo wrote:
>>>> Graham,
>>>> 
>>>> I've finished responding to all of your feedback [1] to prov-o.
>>>> 
>>>> http://aquarius.tw.rpi.edu/prov-wg/prov-o reflects all changes.
>>>> 
>>>> Please feel free to review our responses and the latest draft and make any more comments.
>>>> 
>>>> You may indicate your dissatisfaction by changing the designation to REOPENED (see the beginning of the page).
>>>> 
>>>> Regards,
>>>> Tim
>>>> 
>>>> [1] http://www.w3.org/2011/prov/wiki/Review_of_prov-o_july_3_2012_for_last_call#Graham
>>>> 
>>> 
>>> 
>> 
>> 
>