IVOA Standard Documents V2.0 Proposed Recommendation: Request for Comments

The IVOA Document Standards describes the types of official IVOA documents and the process by which documents are advanced from Working Drafts to formal Recommendations and from Notes to Endorsed Notes. V2.0 implements Endorsed Notes and Errata.

Latest version of IVOA Standards Document can be found at: http://www.ivoa.net/documents/DocStd/20160923

Reference Interoperable Implementations

Endorsed Note process tested with the XML Schema Versioning Policy http://wiki.ivoa.net/twiki/bin/view/IVOA/XMLVersRFC

Other reference implementations to be discussed with the TCG members.

Implementations Validators

Not relevant

RFC Review Period, including TCG Review: 25 September 2016 - 5 November 2016

The community, including the TCG members, is invited to provide comments before Trieste Interop meeting (21 October 2016).

TCG Vote: 6 November 2016 - 20 November 2016

Comments from the IVOA Community during RFC period: 24 September 2016 - 5 November 2016

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from Markus Demleitner

(1) In "1. Document Types", I think the stark distinction between Endorsed Notes and Notes may be confusing rather than clarifying. I can very well imagine that some content is put into a note, goes through an iteration or two, and it is eventually realised that some more formal process should be taken. Sometimes it may be going towards a REC, sometimes towards an EN, and there's no way to tell when first publishing the note. So, I'd suggest to make this:

The IVOA publishes two types of documents:

[Rec track as existing]

IVOA Notes. An IVOA Note is a dated, public record of an idea, comment, or document. Authorship of a Note may vary greatly (e.g., by an IVOA Working Group, by an IVOA member, etc.). A Note can stand as is, or it can initiate or contribute to the development of a Working Draft. Finally, certain Notes may enter a wider review process as a Proposed Endorsed Note (PEN). A successful PEN becomes an Endorsed Note (EN).

-- or we just refer to sect. 2, which essentially has it all as well.

(2) in Sect. 1, the docment repository URL is given as http://www.ivoa.net/Documents/ (uppercase "D"). Retrospectively, I believe the uppercase was an editorial oversight -- lots of links later used lower case, and in implementation, there's a symlink from documents to Documents. However, it's too late to fix this now. To work towards unique URLs (e.g., to enable string comparisons), I'd propose stressing the uppercase D is intentional. Perhaps inserting "(please note the uppercase D)" would already do the trick.

(3) At the end of Sect. 1, WD, PR, and REC apparently are link anchors (underlined blue; my UA does not see the links, by the way), whereas PEN and EN are not. I'm all for consistency here -- either all of them or none of them should carray links.

(4) 1.1 Sets high requirements on status texts ("whether implementation experience is being sought"; "where to send comments") that in practice are never met. This would mean all our standards are non-compliant, which I'd rather avoid. As a quick (if somewhat technical) fix, I suggest replaxing the "must"s in here with "should"s. I think most of the categories mentioned in 1.1 should indeed (and mostly are) be represented in the document header. However, the structured (fielded) form is, I claim, much preferable where applicable. As a longer-term solution (could be 2.1 material), I'd therefore say formalising the document header fields ("title page") for our documents would be a worthwhile effort.

(5) In 1.2, list item 4, the text talks about "multiple versions" when it actually means "revisions"; version is defined in list item 3, and multiple versions would actually be possible. My suggestion: delete the entire parenthesis. Alternative: write "revision" instead of version.

(6) I'm unhappy with 1.2, list item 5's "MIME type conventions". First, because it should be "media type" by RFC 2046, and second because I'm pretty sure none of the MIME RFC actually talk about file extensions. Let's just write "An extension (.html, .pdf, .txt), indicating the media type."

(7) I'm not sure I'm a big fan of the indication that WDs "usually" start with 0.1 on p.4. It's been a long while since I've seen a WD that has not already used the target version of the later PR (1.0, 1.1, whatever). I think that practice is sane, even before REC-1.0. Thus, I'd suggest to replace the first bullet point on p. 4 with: "Documents on the REC track typically carry the version number of the REC they lead up to (1.0 for the initial version, 1.1 for a minor update, etc)."

(8) p. 5 "In formation" -> "Information"

(9) In 1.4, the document contains a solid measure of implementation banter (tar, zip, absolute path names, the on-line form, web uploads). I'm uneasy with having all this detail in the normative standard; for instance, it could be that we change the web page to allow incemental uploading of individual files, Springer-style. Or (which would be far more interesting for me) we might provide a submission API. Or sumission could be just pointing the DC to a certain project within Volute. So, why not just say:

Documents are entered into the IVOA document collection by the Document Coordinator in response to a request from a Working Group chair or the person primarily responsible for editing a particular document. The technical details of the submission process are determined by the document coordinator together with the TCG. Current information is available on a web page linked from the IVOA document repository (cf. sect. 1.2).

(9) I wonder where the language "Such additional items are considered part of the implementation but not part of the standard itself." came from. I'm sure it's wrong in effect and is practically violated by many standards for which the text contains nowhere near enough detail to uniquely match what an accompanying schema (say) says. Turning this into a formulation that reflects practice, respects the original spirit, and makes sense appears really hard, though, and I'm not concerned enough to try. I suppose standards will just continue to do whatever serves them well.

(10) In 1.6, - should be written - for consistency.

(11) p. 6 "announced on the full VO community" -> "announced to..."? Native speakers please work out something that doesn't sound to spiritual here.

(12) p. 7 "redactional changes"; I'm told that "editorial changes" probably conveys better what we mean here.

(13) p. 7 after the sentence with "permantently frozen": I just notice this should have something like "In a last edit, WG chair or document coordinator record the acceptance date (and hence the freezing day) of the erratum." I think something like an Accepted: field is really important to let people quickly assess the erratum.

(14) p. 7 still has "as well as in the heading section of the actual standard text in the version the erratum is written for." I thought we had agreed that we should avoid the need for editing finished documents and would rather have a fixed link to the errata page in the document header?

(15) p. 7 "document begins as a Working Draft" -- I'd suggest inserting "on the recommendation track" here, as neither Notes nor Errata start as Working Drafts.

(16) p. 9 "After a publication period of at least two weeks..." -- actually, I think we've been starting RFC with the publication of the PR in recent years. What's the purpose of this two-week hiatus? At least the announcement of the availability of the new PR should go out via interop@ immediately, no?

(17) As I've pointed out serveral times during preliminary discussion, I'm fairly unhappy with the description of the review process in 2.2. In reality, I can't remember we've ever sent something back to WD, which leads me to expect we won't in the future, either. Instead, documents were edited in PR, with repeated PRs issued one after another. I admit that that's not optimal, but mainly because review periods were too long and tracking of re-issues of PRs would need improvment. In a mail to the tcg on Sept 6 I had proposed language like

"The WG chair may issue additional document versions in order to reach a consensus."

-- which was supposed to mean that several such 4-week periods might be necessary (as indeed they have been in the past). I think that's a bigger issue and my be 2.1 material. I just note for the record my concern that the document here deviates from existing procedures, and since I don't see that we'll see more binary "no"s in the review process in the future, I consider the existing procedure a good thing in order to ensure we issue sensible, well-reviewed standards.

(18) In Sect. 3, "Process", should make clear how the TCG decides. I'd hence propose to change the enumeration to:

1. The TCG unanimously decides that there is no need for a Request for Comments and decides to promote the Note directly to Endorsed Notes.

2. Otherwise a Request for Comments following the procedure described in Section 2.2 is initiated. The Note then changes to Proposed Endorsed Note (PEN) status.

Similarly, it might be wise to state whether an exec decision to pull an EN has to be unanimous, with majority, or whether a single veto is enough.

-- MarkusDemleitner - 2016-10-13

• The title in the document metadata is 'Microsoft Word - PR-DocStd-2.0-20160923.doc', change this to something more appropriate ? -- DaveMorris - 2016-09-29

-- Comments by Tom McGlynn

• This document has always been an odd duck in the IVOA standards. It describes an IVOA process which should be of essentially zero interest to anyone outside the IVOA. In fact, I believe that this document is an excellent example of something that should be an endorsed note.
• The statement about validation (above in this document) is a bit too strong. Although software validation may not be possible within our current framework (thought it might be if we were more specific about our document formats), the process itself requires manual validation by the WG and TCG heads.
• In the example giving the history of a document, there are separate revisions for the RFC and TCG reviews. Since those are no longer separate perhaps some of these should be deleted.
• I am concerned that the errata process is too rigid and will suppress the rapid dissemination of information needed to effectively use protocols. However it seems like there is very little structure given for what errata should contain. It seems like errata should be required to explicitly identify original wording, and the new wording. If elements are to be deleted or added from the document, then the surrounding text should be identified. I think the errata will be much easier to use if they are fully contained within a single Wiki document. This could be separated into two sections: approved and unapproved. I believe anyone should be allowed to edit the unapproved section of the document while the approved section would be updated using the procedure discussed in the document. I would recommend that the errata document include not only the errate themselves, but also permit discussion of the errata at least while they are unapproved.
• There is discussion of documents which are no longer under development. Such documents should be identified in the document repository. Presumably that includes at least SkyNodes, maybe STC-S?
• There is a statement that all features of the proposed draft are to be implemented before moving to approval. I suspect that that has almost never happened in standards of any complexity.

Comments from TCG members during the RFC/TCG Review period

WG chairs or vice chairs must read the Document, provide comments if any. After the RFC period they have to formally indicate if they approve or not the Standard.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair ( _Matthew Graham, Pat Dowler )

Applications Working Group ( _Pierre Fernique, Tom Donaldson )

Data Access Layer Working Group ( François Bonnarel, Marco Molinaro )

Data Model Working Group ( _Mark Cresitello-Dittmar, Laurent Michel )

Grid & Web Services Working Group ( Brian Major, Giuliano Taffoni )

We could consider adding more detail about what constitutes implementations and validators as there has been much discussion on that topic in the Operations IG of late.

And (perhaps this is too detailed) there is not much text about creating new versions of standards. What is the difference between major and minor version increments? And, assuming it becomes endorsed, the schema versioning note could be mentioned there.

I noticed a small typo in 1.3: "In formation" should be "Information".

-- BrianMajor - 2016-10-14

Registry Working Group ( _Markus Demleitner, Theresa Dower )

Registry is largely unconcerned. We would appreciate a: "The WG chair in cooperation with the document editors should prepare a StandardsRegExt record for the new REC and submit it to the RofR." in 2.3, ongoing work. One could add urges to update standards records in the ongoing work paragraphs of WD and REC (or even NOTE) sections, too, but as long as there's no software actually using such information, there's probably no great need for that.

On the long run, this document should probably also say under which circumstances keys can be added to standards records (e.g., TAPRegExt should have added keys to TAP rather than its own record), but that's probably 2.1 material (or material for a separate EN).

-- MarkusDemleitner - 2016-10-13

Semantics Working Group ( _Mireille Louys, Alberto Accomazzi )

Education Interest Group ( _Massimo Ramella, Sudhanshu Barway )

Data Curation & Preservation Interest Group ( Francoise Genova )

Knowledge Discovery in Databases Interest Group ( Kai Polsterer )

Operations ( _Tom McGlynn, Mark Taylor )

Theory Interest Group ( _Carlos Rodrigo )

Time Domain Interest Group ( _John Swinbank, Dave Morris )

Standards and Processes Committee ( Françoise Genova )