Re: [oslc-core] Position of resource shapes in resource preview spec (was: Version Control Commit by sspeiche)

Make that:

That way the "progressive disclosure"
goes: (1) general description, (2) normative description, (3) index of
things that are used/referenced by those descriptions (vocabulary specifics).

The general non-normative description
gives the context for the normative description, and the normative description
gives the context for the tables. I don't think the tables help set-up
the context for the normative description. If people want them, they can
follow the link the first time they're mentioned (at which point they have
at least a little context) rather than having them presented before the
normative description has said where they're used.

M

From:      
 Martin P Pain/UK/IBM@IBMGB

To:      
 ,
Steve K Speicher <>

Date:      
 21/08/2014 11:36

Subject:    
   [oslc-core]
Position of resource shapes in resource preview spec (was: Version Control
Commit by sspeiche)

Sent by:    
   <>

Quick feedback:

I suggest the resource shapes definition goes further down - probably at
the end, just before the appendices. When reading through it in order,
the definition of the properties & classes may make sense at that point
(between the non-normative intro & the normative stuff) as they give
an overview of the data in use, but I think the resource shapes don't make
sense until you see them in use (i.e. in context) in the normative text.
(So a link from the normative text to the appropriate shapes further down
the document would make sense). 

Having said that the properties & classes may make sense that early,
in specs where there are more terms than this one then I would suggest
that the properties & classes move down to the bottom as well. So perhaps,
for pre-emptive consistency, we should move it all to the bottom.

That way the "progressive disclosure" goes: (1) general description,
(2) normative description, (3) things that are used/referenced by those
descriptions (vocabulary specifics). 

Especially as the vocab terms are part of a vocab, separate from the spec,
in a sense they are external references. (Although we might in that section
define how they are used by this spec - but I expect that would be a summary
of what's in the normative description anyway.) 

[I know this is a work-in-progress - this feedback is my contribution to
that progress :) ] 

Martin

<> wrote on 20/08/2014 03:05:56:

> From: 

> To:  

> Date: 20/08/2014 03:05 

> Subject: [oslc-core] Version Control Commit by sspeiche

> Sent by: <>

> 

> Author: sspeiche

> Date: 2014-08-20 02:05:56 +0000 (Wed, 20 Aug 2014)

> New Revision: 15

> Web View: https://tools.oasis-open.org/version-control/browse/wsvn/

> oslc-core/?rev=15&sc=1

> 

> Modified:

>    specs/resource-preview.html

> Log:

> Added sections for separate terms and shapes, also proposed doc 

> structure changes.

> 

> 

> ---------------------------------------------------------------------

> To unsubscribe from this mail list, you must leave the OASIS TC that

> generates this mail.  Follow this link to all your TCs in OASIS
at:

> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

> 

Unless stated otherwise above:

IBM United Kingdom Limited - Registered in England and Wales with number
741598. 

Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU

Unless stated otherwise above:

IBM United Kingdom Limited - Registered in England and Wales with number
741598. 

Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU