Re: [xri-editors] PLEASE PROOF: [xri-editors] Groups - xri-syntax-resolution-1.0-cd-PROOF.doc

["Karl F. Best" <karl.best@oasis-open.org>]

Drummond:

This is a long list of questions, so it's taken me a while to get to a 
reply. Some of this is answered in the TC Guidelines document at 
http://www.oasis-open.org/committees/guidelines.php but other parts are 
things that we haven't figured out yet or haven't built a solution for yet.

> But we still need our OASIS reference questions answered so we can lock
> the document for the vote. I note that we looked at the TC Process
> documents for guidance about Committee Drafts in this respect and didn't
> find anything about this subject of final changes at all, even though
> based on our experience this must be a scenario every TC goes through.
> Can I suggest that OASIS produce a document that specifically addresses
> the process for producing a finished Committee Draft? Questions
> addressed in this document should include:
>  
> * Naming conventions, and how to deal with them up until the FINAL "cd"
> draft.

There's a final draft of a naming scheme at 
http://www.oasis-open.org/spectools/docs/chairs-filenaming-02.html (link 
from near bottom of the SpecTools page at 
http://www.oasis-open.org/spectools/index.php). This is not yet official 
or enforced, but I would recommend that you use it because something 
close to this is likely to be approved and enforced soon.

> * Errata document references (specifically, the questions in the email I
> sent on 12/23 to Karl about how to include a reference to this doc when
> one doesn't exist yet).

My answer yesterday was to refer to an empty document and add content as 
you go.

> * How to handle references to other related TC documents (such as a
> primer, or conformance specs, or other related specs) esp. when they are
> planned and not actual yet.

We don't yet have a policy for Normative References (referring to a doc 
outside of OASIS) but are working on this. But I don't think that's what 
you're asking. As with the errata doc above, I would suggest creating an 
empty document, linking top that, and adding content over time. This 
assumes, of course, that the target document has a persistent name 
and.or URL, which is entirely another matter.

> * How to handle Acknowledgements.

The official specification document templates (see 
http://www.oasis-open.org/spectools/index.php) have an Ackowledgements 
section -- the first appendix, I believe. You must use these templates 
for your specs.

> * How to handle Revision History (what levels of changes to record and
> when).

It's up to the TC to figure out what's a major vs. minor rev. The rev 
level should be reflected in the filename, following the file naming 
scheme I referenced above.

> * How/when to obtain an OASIS persistent identifier for the document.

Select the file's permanent name (as above), then send a request to 
webmaster@oasis-open.org to create a redirect that will link to the 
latest version of the file in the doc repository. Whenever you check a 
new version of the file into the repository you'll have to ask the 
webmaster to update the redirect.

> * How/when/if to publish the spec in multiple formats (Word, PDF, HTML,
> DocBook).

The approved templates (above) are provided in multiple formats. Take 
your pick. There will soon be a policy that TCs must provide both source 
(XML, HTML, Word, etc) as well as compiled (PDF) versions for archive; 
there's a number of docs that we may not have source for.

> * Who to notify about the vote, the posting, etc.

The TC Process requires that the TC Admin (Jamie and I) be notified when 
the TC conducts a vote to approve a Committee Draft. Otherwise it's up 
to the TC to keep the lkatest version of the doc posted in the repository.

> * How and when to get a link to the final spec added to the TC home
> page.

If by "final spec" you mean an approved OASIS Standard, I'll take care 
of adding links to the OASIS home page etc. For the TC to add to your 
page, you just submit the docs into the repository then they'll 
automatically appear at 
http://www.oasis-open.org/committees/documents.php?wg_abbrev=xri

-Karl



>  
>  
> Like the final finishing details on a new house, the process of
> finishing a Committee Draft is actually much more difficult and labor
> intensive than it looks. It would really help to have a guidance
> document devoted just to this step (and potentially including all the
> subsequent document processing steps to advance to an OASIS Standard).
>  
> Thanks for your help,
>  
> =Drummond 
>