Re: [oslc-core] Initial feedback in response to your request for pre-review comments

["Jim Amsden" <jamsden@us.ibm.com>]

Chet,
Thanks for the initial feedback. Responses
are included below in <jra> tags (primarily to put a record of the
response in the oslc-core mailing list).

I have created ReSpec issues for the
changes that require ReSpec updates:
  1. Rename the generated Conformance
section to "Typographical Conventions"
  2. Add a new ReSpec section for
references so these can be positioned in the document (they are currently
the last section)
  3. Add "Appendix "
as a prefix to the title of all appendixes 

We understand there could be more ReSpec
changes required once we have the metadata and other changes that will
need to be made to align the current files with the OASIS published work
cover page format.

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 Chet Ensign <chet.ensign@oasis-open.org>
To:      
 oslc-core@lists.oasis-open.org
Cc:      
 OASIS TAB <tab@lists.oasis-open.org>
Date:      
 03/09/2016 03:15 PM
Subject:    
   [oslc-core]
Initial feedback in response to your request for pre-review comments
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

Members of the OSLC Core TC, 

In response to your request for a pre-PR check by the
TAB, I have taken a first look at your documents. The TAB will have more
feedback next week. For now, I have some immediate comments to share: 

1. You are creating the working drafts in ReSpec. This
is very cool. Generally when a TC uses something other than ODT or DOC
for their spec drafts, I deputize the editors to act as agents for TC Admin
in preparing the final files for publication. For example, I send instructions
on how to do the This version links and Latest version links. 

  Unless you have a concern about that, I will plan
on doing the same here. Because these are changes made at the direction
of TC Admin, the updated documents do not need to be re-approved by the
TC. 

  Please let me know if you have any concerns around
this. 
<jra>This is fine. As the OSLC Core
editor, I will be happy to work with the TC Admin to create the final publication
files.</jra>


2. Organization of the work (documented in https://issues.oasis-open.org/browse/TAB-1383.) 

  The current working draft is a set of 8 HTML documents
drafted in ReSpec. They are based off the format of the template that Paul
sent the TC. However, it does not appear that we ever discussed with the
TC how the work should be constructed as we normally would have done when
responding to Template requests. So we don't know whether the TC intends
this to be one spec, a multi-part spec, or 8 individual specs. 

  Please let me know your intentions on how the work
is to be published. If you'd like to discuss, let me know and I'll set
up a time when we can talk. 
<jra>OSLC Core is a multi-part specification.
We understand that will affect several aspects of the cover page material
that will need to be addressed.</jra>


3. Acknowledgements section (documented in https://issues.oasis-open.org/browse/TAB-1379)
 In the Working Draft, the Acknowledgements section is a single sentence
thanking "everyone who worked on the spec" (paraphrased). 

  The TC Process section 2.18 requires that the section
"include a list of people who participated in the development of the
Work Product. This list shall be initially compiled by the Chair, and any
Member of the TC may add or remove their names from the list by request." 

  Unless these are 8 separate Committee Spec Drafts,
you only need to include the Acknowledgements section in the first document.
The section should list all current and any past TC members from the TC
during the development of the specs. It should list both their name and
organizational affiliation. (E.g. Chet Ensign, OASIS) 
<jra>I will update this section with
all the current and past TC members who contributed.</jra>

4. A couple of comments on organization (documented in
https://issues.oasis-open.org/browse/TAB-1380) 

4.a The references are currently in an Appendix of the
document. While not required by the TC Process, the common practice across
all approved work products has been to include these at the beginning of
spec documents, generally in section 1. 

4.b  There is also a section 2 in the documents titled
"Conformance." It includes a general statement about normative
/ non-normative sections and the statement about use of keywords. 

    I found this confusing because I thought
it was intended to be the Conformance Clauses section. It wasn't until
I found section 7 "Implementation Conformance" that this was
cleared up. 

To address both of these, I strongly recommend using an
organization like: 

- 1 Introduction 
  1.1 Terminology 
  1.2 References 
  1.3 Typographical Conventions 

(See OData Part 1 for a practical example: http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398196.)

Here, "Conformance" would become 1.3 (titled
'Typographical Conventions' but you could just a different title - just
please, not with the word "Conformance."). And the Normative
and Non-Normative References would go under 1.2 References. 

  This would align the OSLC documents with the layout
of almost every other specification published by OASIS. 
<jra>I will make these changes, along
with the updated templates (which may result in some ReSpec updates). </jra>

5. I will collect miscellaneous editorial corrections
needed to match the OASIS template. (They will be documented in https://issues.oasis-open.org/browse/TAB-1382.) 

For now, two quick ones: 

5.a Appendices in the working draft just start with a
letter, e.g. "A." - They should be in the form Appendix A. <title> 
<jra>Fixed</jra>

5.b  Please make Change history the last section
in the document. This aligns with common practice across all TC work products.
<jra>Fixed. But I wonder if we could
remove this section and rely on the change history in SVN? We havn't been
keeping this section up to date since it was redundant with the comments
added on checkin. If this section is needed, I will have to pull the history
on each document and summarize the key changes here.</jra>

We'll provide more feedback once we can go over the work
in depth. Most immediately, please let me know: 

- Whether you are fine doing edits to produce the final
output at my direction. It will probably get us through the changes needed
faster. 
<jra>Yes, no problem</jra>

- How you are intending to organize the work: 1 spec document,
a multi-part spec, or 8 separate specifications. 
<jra>multi-part spec.</jra>

Thanks! 

-- 

/chet 
----------------
Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393