Re: [coel] OASIS documents overview

Hi Joss,

I can give you some feedback on these questions.

On Fri, Sep 25, 2015 at 9:25 AM, Joss <Joss@activinsights.co.uk> wrote:

For all documents

· How relevant is the date at the top of page 1 and in the footer?

For your working drafts, it isn't critical. It is simply whatever date you want to use to indicate when the draft was written or completed. When we publish your approved work - e.g. when you release it for public review - we set this to the date the TC approved the document. So, for example, if the TC approved a motion to submit the document for public review at its Sept. 25th meeting, that is the date we would put there.

· We should probably have ‘Additional Artifacts = none’ for every document except COEL

Yes that's fine. The additional artifacts section is just to list any other components, such as schemas, that are part of that specific specification. If a specification document is complete and has no other pieces that go with it, then you can make it none so that, when we publish it, we will know not to look for anything else to go with it.

· We can probably now have a set list of related works for all docs

Yes - I would list out all the related specifications there.

· We need to hyperlink all URI patterns on all docs and check they (most do not at the moment)

On the front page of the spec, we will do that when we publish them. We use the Latest Version links since those always point to the most up to date version of the spec. See how this is done in the KMIP spec: http://docs.oasis-open.org/kmip/spec/v1.2/kmip-spec-v1.2.html

The template you are working in should have both the "This version" link and the "Latest version" links for each document. Note that these are the locations where the documents *will* be published so those links will not work until we have published your work the first time around.

For normative and non-normative references in the body of the spec, you'll need to check links yourselves.

·         Table of contents need to be updated on each revision

·         We need to add normative references within the specification as we move down the hierarchy (& link correctly)

·         We need to review the external normative references for each doc (& link correctly)

·         Are there some standard non-normative references (e.g. Data to Life)?

On references generally, please note that the requirement for them is that any external content you cite in the body of the spec needs to be listed here. So for example if you cited to Key Management Interoperability Protocol Specification Version 1.2 for some reason in the body of the document in a section on security (just making this up of course), then you would include the reference in the references section.

There is no need to list references that aren't mentioned in the body of the specification. Certainly, nothing should appear under Normative References that isn't used elsewhere in the spec since, by making it Normative, you are in essence saying that people implementing your spec will also need to use some or all of the Normatively referenced spec.

· There are some style questions to harmonise (does OASIS have a standardised approach?):

Nope, we don't have any governing styles on these.

o   Use of defined terms, Capitals and CAPITALS

o   Abbreviations (e.g. Behavioral Atoms / Atoms) - when to use?

o   Acronyms (e.gs IDA) - when to use?

·         The spelling of Activinsights is incorrect in the Acknowledgement sections of a few docs

·         We should standardise our date formats in the revision section

·         Should we be using track changes in Word?

If you do use the track change feature, I ask that you accept all changes in the working draft that the TC approves as a Committee Specification Draft. I sometimes get drafts with the change tracking still turned on and then I have to accept all the changes and I hate doing that myself because then what if something is wrong there? Then it looks as if I messed the spec up in publishing it. Likewise, I recommend removing any comments embedded in the draft since they will go out with the publication. (I do not remove comments.)

Let me know if you have any questions on any of this...

/chet

PQI

·         COEL-1 Do we want to include pub/sub specifications at this stage or at all?

·         COEL-4 Audit of leavers. This is labelled as an MMI but I think it is more of a query. We don’t have to have this in the standard and it might be better as a Coelition commercial contract point.

·         COEL-5 There is benefit for Service Providers being able to work in their own time zone. Can we include this now?

·         COEL-9 It could very beneficial for all Service providers to be able to query against the segment data as well as the atom fields.

BAP

·         2.2.1 Should we explicitly link “queryURI” and “managementURI” either in or to the MMI and PQI documents?

·         2.2.1 & 2.2.2 We need to agree the standard format for example code

·         2.4 I have added a section for ‘exceptions’ to provide a way of managing issue COEL-6

·         3.7 I have added a link to the IDA in the ‘who’ section to sort out issue COEL-18

COEL

·         I have suggested a document structure for the COEL high level specification

Joss Langford

Technical Director

Activinsights Ltd

Tel: 01480 862080

MBL 07712 886208

www.geneactiv.co.uk

Important Information: The contents of this email are intended for the named addresses only and contain information which is confidential and which may also be privileged. Unless you are the named addressee (or authorised to receive for the addressee) you may not copy, use it, or disclose it to anyone else. If you received it in error, please notify us immediately at enquiries@activinsights.co.uk and then destroy it. Further, whilst we make efforts to keep our network free from computer viruses, etc., you do need to check this email and any attachments to it for viruses as we can take no responsibility for any viruses which might be transferred by way of this email.

Activinsights Limited, Unit 11, Harvard Industrial Estate, Kimbolton, Cambs, PE28 0NJ. A company registered in England & Wales. Registered number: 06576069

/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

coel message