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.

Version of IVOA Document Standards initially submitted to RFC: http://www.ivoa.net/documents/DocStd/20160923

Version of IVOA Document Standards taking into account the comment received during the RFC: http://www.ivoa.net/documents/DocStd/20170329/

Version of the IVOA Document Standards taking into account the last comments received during TCG vote: http://www.ivoa.net/documents/DocStd/20170424/

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: 31 March 2017 - 14 April 2017

Please check the answers to RFC/TCG comments and vote here

---

---

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.

Comments FGenova, 21 March 2017: Notes can also be at the origin of RECS, not only of ENs. Original wording not changed in the document.

(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.

Comments FGenova, 24 March 2017: Changed to lowercase d after discussion with Markus and Marco.

(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.

Comments FGenova, 21 March 2017: Done

(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.

Comments FGenova, 21 March 2017: The only 'must' is to include a section about the status of the document. The content of the status section is already a 'should'. OK to work on the document header at a later stage, also in connection with the landing page improvement.

(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.

Comments FGenova, 21 March 2017: 'version' changed to 'revision' in the parenthesis. ',but this should not be a major problem' deleted from the parenthesis as suggested in another comment.

(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."

Comments FGenova, 21 March 2017: Done

(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)."

Comments FGenova, 21 March 2017: The text already states that the public version starts at 1, which is when they begin the REC track. Beginning at 0 when the text is in WG allows for successive versions with significant changes. The move from 0 to 1 when the document becomes public also signs the status change. Original text kept in the document.

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

Comments FGenova, 21 March 2017: Done

(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).

Comments FGenova, 21 March 2017: Text of Section 1.4 updated to:

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. Absolute path names must be avoided when packaging the document(s) as well as when creating internal links within the document.

When problems are encountered during the submission process (e.g., unavailability of the site or too large files), it is necessary to agree with the DC on different means of electronic transfer.

(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.

Comments FGenova, 21 March 2017: No change in the text thus.

(10) In 1.6, <ConciseName>-<currentversion> should be written <ConciseName>-<CurrentVersion> for consistency.

Comments FGenova, 21 March 2017: Done, also for RunningNumber a few lines below.

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

Comments FGenova, 21 March 2017: Done. Changed to 'announced to'

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

Comments FGenova, 21 March 2017: Done. Changed to 'editorial changes'

(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.

Comments FGenova, 21 March 2017: Done

(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?

Comments FGenova, 24 March 2017: Deleted. Mention of the link to create in the header of the REC document added in the first paragraph of the Errata section.

(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.

Comments FGenova, 21 March 2017: Done

(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?

Comments FGenova, 24 March 2017: Deleted in the text and in the workflow figure.

(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.

Comments FGenova, 21 March 2017: Text changed to

Following the RFC period, the WG chair may issue additional document versions that take into account the comments received in order to reach consensus, or may decide to return the document to Working Draft if the maturity level appears not to be sufficient.

(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.

Comments FGenova, 21 March 2017: The TCG and Exec chairs manage the discussions in their respective Boards and reach a decision. No modification to the text.

-- MarkusDemleitner - 2016-10-13

---

---

---

Comment by Dave Morris

• 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 FGenova, 21 March 2017: Will be checked with the Document Coordinator.

-- 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.

Comments FGenova, 21 March 2017: I see a real interest for IVOA processes in other communities, so it is important that this document is fully managed and properly exposed in the ADS, and later on gets a DOI when we will implement DOIs for our documents. Endorsed Notes fit the purpose. At this stage we have to complete the REC process (not good to change the rules of game while the game goes on) but it is a good topic for discussion and decision by the TCG at its next meeting.

• 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.

Comments FGenova, 24 March 2017: The initial wording about the requirements to have implementation of each feature and validation tools was softened, to clearly allow to waive the requirements and to explain that the rules can depend on the WG.

• 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.

Comments FGenova, 22 March 2017: We now allow several revisions during RFC, I changed the wording accordingly.

• 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.

Comments FGenova, 24 March 2017: Errata structure: The additional information suggested to be required was added (to be provided if relevant). Errata categories: we left the three categories proposed initially (approved, proposed, rejected) to be able to keep track of the errata history for a given document. We also left the structure of the errata page as proposed: it contains the erratum list and each erratum has its own page, to be able to manage, read and print it individually (see Applications' 5th comment below). An erratum page can be modified as long as the erratum has not been accepted or rejected. The possibility to add comments on the Proposed erratum page is explicitly stated. Process flexibility: the possibility to decide on an erratum by email is added.

• 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?

Comments FGenova, 22 March 2017:Reference to 'historical' documents added at all stages of the process and as a function of the document repository.

• 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 FGenova, 24 March 2017: This sentence was deleted (and the wording on the requirement for two reference implementations and a validator changed as explained).

-- TomMcGlynn - 2016-10-19

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 )

• p1 - The status of the document is uncorrect "It is a Note expressing suggestions from and opinions of the editor".

Comments FGenova, 21 March 2017: Updated to the PR status text

• p5 - 1.3 Format. "ivoatex+volute" citation. The "volute" technology is not so well known and its role in the IVOA document generation process should be decribed (collaborative document system...) and may be detailed (just a facility, or a requirement ? What is the role of the Document Coordinator concerning Volute management ?...)

Comments FGenova, 22 March 2017: Explanation on the IVOA usage of volute given in a footnote.

• p6 - 1.6 Errata - It is surprising to have this Errata section before the standards process.

Comments FGenova, 24 March 2017: Errata sub-section moved as a section after the Endorsed Notes one.

• p6 - 1.6 Errata. - A lot of unecessary line feed in this paragraph.

Comments FGenova, 24 March 2017: Updated

• p6 - 1.6 Errata - I am a little bit worry about the fact that an errata is just a twiki page. Concretly it means that these errata cannot be published/printed as a classical document (PDF).

Comments FGenova, 24 March 2017: We did not follow Tom's recommendation to put all the errata on a single wiki page to allow using the wiki function to print individual errata.

• p9 - point 4 "validation tools should be available" - does it really means that all pending PR (notably HiPS) is postponed until such a validation tool will be available ? Are there other PR in this case ?

Comments FGenova, 24 March 2017: The possibility to waive the requirement is more explicit in the text now.

• p12 - Endorsed Notes process - "a lighter weight review process than the one undergone by the IVOA Recommendations..." but in fact, there is no real difference in practice. It is globally the same process due to the fact that most of IVOA standards authors are TCG members. An concerning the role of Endorsed Note, the Tom's idea that this document should be an Endorsed note makes sens for me.

Comments FGenova, 22 March 2017: The process is lighter because it allows the TCG to skip the RfC in cases when the TCG members' opinion is considered sufficient to take a decision. 'optional' added in PEN definition. Have also a look at the Endorsed Note workflow figure. Tom's point on the fact that this document should itself be an Endorsed Note is discussed as an answer to Tom's comment.

• p15 - Appendix - "This document is been produced by [...]" - the "..." should be replaced by TCG ?

Comments FGenova, 22 March 2017: This comment is likely on the Endorsed Note text. Parties other than the TCG can produce Endorsed Notes. Endorsed Notes are endorsed by the TCG.

-- PierreFernique - 2017-03-20

• p5 - 1.3 Format. Typo: "In formation" should be "Information".

Comments FGenova, 21 March 2017: Done

• Some hyperlinks not working:
  • p5 - 1.4 How to publish a document. The hyperlink "on-line form" has a value of http://www.ivoa.net/bin/up.cgi which at the moment generates a 404 "Not Found" status.

Comments FGenova, 22 March 2017: The technical details on the current submission process were deleted from the standard.

• • p8 - "IVOA's mission" and related footnote. http://www.ivoa.net/pub/info/index.html is "Not Found"

Comments FGenova, 22 March 2017: Link updated.

-- TomDonaldson - 2017-03-20

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

- Maybe the xml schema versioning document should be cited in section 1.5 ?

Comments FGenova, 22 March 2017: Done.

- Section 1.6 should be moved at the end of section 2 (or after section 3 if we imagine having errata on endorsed note). The current location of this section 1.6 looks a little bit odd.

Comments FGenova, 24 March 2017: Done: Errata sub-section moved as a section after the Endorsed Notes one. It is useful to have errata also for ENs.

- We could imagine a flow diagram for Endorsed note as well.

Comments FGenova, 24 March 2017: Done.

Apart from these points which are not critical DAL Working group validates the document.

-- FrancoisBonnarel - 2017-01-16

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

-- Document types

• Page 3 top: As the document refers serveral time to Volute, we can specify here that Volute is not in the scope of IVOA effort for the (very) long term preservation.

Comments FGenova, 22 March 2017: Done in a footnote.

• Endorsed Notes track documents: Not necessary to spécify the "Endorsed Note may refer to a REC". Any document may refer to a REC.

Comments FGenova, 22 March 2017: The point here is that the Endorsed Notes may have a reference to a REC in their name.

-- 1.2 Naming and version numbering conventions

• The sentence "(..., bit this should not be a major problem) can be removed

Comments FGenova, 22 March 2017: Done

• html, pdf, doc... are not Mime types but filename extensions

Comments FGenova, 22 March 2017: Done

• Misalignement in the table of examples

Comments FGenova, 22 March 2017: Updated

• Could be nice to specify that changing the version number requires a new REC process

Comments FGenova, 24 March 2017: This is already explained I think at the beginning of the document.

-- 2.1 page 9 top #4

• We can specify here that the rules for the implementation references are specific to the WG matter (DM, DAL..)

Comments FGenova, 22 March 2017: Done

-- 2.4 page 11 top #5

• My understanding was that the editor responds to the comments but the WG chair makes the decison of (not) reverting to the WD

Comments FGenova, 24 March 2017: Udated accordingly.

-- LaurentMichel - 2016-10-26

Approved

-- LaurentMichel - 2017-04-12

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.

Comments FGenova, 22 March 2017: Comments discussed with Brian in Trieste. He accepted to withdraw them.

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

Comments FGenova, 22 March 2017: Updated

-- 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.

Comments FGenova, 22 March 2017: Work on the StandardsRegExt record mentioned at the beginning of 2.3, Ongoing work.

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).

Comments FGenova, 22 March 2017: No change in the document.

-- MarkusDemleitner - 2016-10-13

Semantics Working Group ( _Mireille Louys, Alberto Accomazzi )

On the Semantics's aspects, there was no clash with existing standards. Such a process to validate and publish Endorsed Notes seems interesting to develop controlled vocabularies in the Virtual Observatory. I approve the updated document .

-- MireilleLouys - 2017-03-23

Additional comment received from Alberto Accomazzi on 2017-03-22: in the examples you give which show the evolution of a document through the NOTE/WD/PR/REC stages you use the text "major update to WD in WG; does affect software".

I would prefer using the term "standard implementations" or maybe just "implementations" rather than "software".

Comments FGenova, 24 March 2017: Done.

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 )

---

TCG Vote

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

Applications Working Group ( _Pierre Fernique, Tom Donaldson )

Approved -- PierreFernique - 2017-04-10

Approved -- TomDonaldson - 2017-04-10

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

Approved -- FrancoisBonnarel - 2017-04-12

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

Approved by Laurent Michel 2017-04-14 (see above)

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

Approved -- BrianMajor - 2017-04-11

Registry Working Group ( _Markus Demleitner, Theresa Dower )

Our concerns are sufficiently addressed. Let's go for it. -- MarkusDemleitner - 2017-04-03

Semantics Working Group ( _Mireille Louys, Alberto Accomazzi )

Approved . -- MireilleLouys - 2017-04-10

Education Interest Group ( _Massimo Ramella, Sudhanshu Barway )

Data Curation & Preservation Interest Group ( _Francoise Genova )

Knowledge Discovery in Databases Interest Group ( Kai Polsterer )

Operations Interest Group ( _Tom McGlynn, Mark Taylor )

Final updates follwing comments from Mark Taylor (received 14 April 2017, implemented in the 20170424 PR version)

• in sec 2.4 TWiki page for RFC changed into "globally editable page" for consistency and to defend against future change in technology
• in Sec. 2.1 sentence on implementation references changed to "The rules for implementation references can be specific to a working group."
• in sect 2.2, homogenized the fact that Chair and Vice-Chair are required to examine PR but a single input is sufficent provided that they work in co-operation

Theory Interest Group ( _Carlos Rodrigo )

Time Domain Interest Group ( _John Swinbank, Dave Morris )

Standards and Processes Committee ( Françoise Genova )

---