[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [oslc-core] Initial feedback in response to your request for pre-review comments
Chet, thanks for your quick initial review.
We intend to submit a multi-part specification.
Nick Crossley has volunteered to update Re-Spec to address the issues related to the document structure rather than editing the output documents directly. As for individual edits unrelated to structure, we are happy to apply them to the input documents as requested.
Regards,
Dr. Martin Sarabura
R&D Fellow, PTC
From: oslc-core@lists.oasis-open.org [mailto:oslc-core@lists.oasis-open.org] On Behalf Of Chet Ensign
Sent: March-09-16 3:13 PM
To: oslc-core@lists.oasis-open.org
Cc: OASIS TAB
Subject: [oslc-core] Initial feedback in response to your request for pre-review comments
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.
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.
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)
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.
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>
5.b Please make Change history the last section in the document. This aligns with common practice across all TC work products.
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.
- How you are intending to organize the work: 1 spec document, a multi-part spec, or 8 separate specifications.
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]