IVOA Document Standards RFC

This document will act as RFC centre for the IVOA Document Standards 1.10 Proposed Recommendation.

Review period: 16 September 2008 to 15 October 2008

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

Discussion about any of the comments or responses should be conducted on the Standing Committee on Standards & Processes mailing list, stdproc@ivoa.net.

Comments

Responses by BobHanisch reflect the consensus of the Standards and Processes Committee (FrancoiseGenova, ChristopheArviset, BobHanisch) and the Document Coordinator (BrunoRino).

• Definition of Terms : by DickShaw : The term "technical report" in paragraph 1, sentence 2 of Sect. 1.1 has not been defined. It appears to be a synonym for "IVOA document" but this should be clarified.

Agreed. This and other occurrences of "technical report" have been replaced with "document".

• Reference to Doc Standards Management : by DickShaw : It would be helpful to include a reference (and link) to IVOA Note 2004-April 25, "Guidelines and Procedures for IVOA Document Standards Management" since it provides useful, additional "how to" advice about developing IVOA documents.
  • NormanGray: +1, but mightn't it be more sensible to merge the content of that document into this one -- it's not clear to me what the distinction between the documents is.
  • BrunoRino: I support (both).

The revised document includes essential text from the Note, and thus should be a complete picture of the IVOA standards process.

• Referencing IVOA Documents : by DickShaw : It would be very helpful to explain (or better, to point to another document that explains) how to reference IVOA documents in external publications. That is, this document should point to information about how the citation should read, what the most appropriate URL/URI is, and whether there is a DOI or other external system used for referencing, etc. As an example from another context, were I to cite the FITS standard in a paper or presentation, my reference list would include:
  • FITS 2008, Definition of the Flexible Image Transport System, IAU FITS Working Group (Version 3.0; Greenbelt, MD: FITS Support Office, NASA/GSFC); available on-line at: http://fits.gsfc.nasa.gov/fits_standard.html
  • +1 from NormanGray. A stable URI and a DOI would be good. There was some on-list discussion about this a while ago -- should that be folded in here (http://www.ivoa.net/forum/interop/0806/79index.htm)?
  • BrunoRino: A stable URI does exist in the form of http://www.ivoa.net/Documents/latest/SHORT_NAME.html although I would rather have http://www.ivoa.net/Documents/SHORT_NAME and that URI should present the whole history of the document.

We agreed to adopt the convention suggested by Bruno, so there will be a single URI that points to the document and its history. We are also working with the ADS to incorporate IVOA documents into their system.

• S1.2 Naming convention : NormanGray :
  • The use of 'the short name' in this section might be clearer if the first two sentences were replaced with As well as its title, every document should have a one-word 'short name', which should be consistently used in URIs, and which should be chosen in consultation with the DC

This wording will been changed once we have reached a more general agreement on naming and numbering of IVOA documents.

• • The final sentence is EXT should follow MIME type conventions -- is this intended to have more force than just EXT should be the conventional file extension for the document type? MIME registrations don't typically mandate file extensions: RFC2854, for text/html, simply indicates that .html and .htm are common, but that there are multiple possibilities. Perhaps the most that could be said is for the final sentence to be HTML and PDF files should have the file extensions ".html" and ".pdf" respectively; for other files, EXT should be the conventional file extension for the document type.

We do not see a reason to make the IVOA document extensions more restrictive than those in general use on the Internet.

• • Some recommendations have auxiliary files which may most naturally live alongside the document, but which in some circumstances (I'm thinking of the Vocabularies document) ought to live elsewhere in the ivoa.net tree -- should this document discuss this? If so, this section would be the obvious place.

A description of auxiliary files (XML schema, RDF vocabularies, and WSDL files) has been added.

• S1.3 Format : NormanGray :
  • I suggest permitting XHTML as well as HTML, as long as it's served with MIME type application/xhtml+xml (RFC3236). If one is generating the document text as part of an XML toolchain, it's an errorprone extra step to convert it to HTML (I've run into this problem, and getting it completely right took more iterations than I expected).
    • BrunoRino : I disagree; that would mean that one of HTML, XHTML or MSWord is required. I would do the opposite actually: mandate one and only format (I am thinking of the reader here, he is the one that should not have to make too much efforts)
    • PaulHarrison: my reading of the current wording is that XHTML is already allowed - there is no specification of which version of HTML is required and my interpretation is that XHTML is a subtype of HTML. - the W3C regard XHTML as part of the "HTML" activity http://www.w3.org/MarkUp/Activity. Note that MSWord is not a required format - personally I would ban the use of MSWord/Openoffice and all non-native html editors - we could then ensure a much more consistent style across the documents - there are RECs that seem to have been published without providing even the HTML form - e.g. http://www.ivoa.net/Documents/latest/SSOAuthMech.html

As above, we prefer to simply follow general practices for documents published on the Internet. We also did not feel it was appropriate to ban the use of Word given its widespread use and convenience in terms of tracking revisions to documents. We will, however, insist on every document being available in HTML and suggest that PDF versions also be provided. The text has been updated accordingly.

• • Similarly, it might be worth suggesting that documents are encoded as UTF-8. This involves some technical adjustment on the part of the DC, but as before avoids the necessity for awkward and errorprone steps in a generation toolchain, as well as being most straightforwardly conventional these days.
    • BrunoRino : Although that is a technically sound option, it goes against common practice. It is far too common to receive html files with latin-1 encoding, which is currently the default. And it is far too difficult to change such practices.

We accept Bruno's recommendation to leave things as is.

• S2.2 Proposed Recommendation : NormanGray :
  • The second sentence after 'Next maturity level' ends ...and announced on the website. It might be useful to clarify just which website this is. I presume it's ivoa.net, but it's not otherwise mentioned, and it's not clear just where the announcement should be. Also, it might be useful to indicate how one goes about arranging this (does the DC do it?)
    • BrunoRino : The current practice is a link to the RFC page on the document table (http://www.ivoa.net/Documents/)

This has been clarified in the document.

• MarkTaylor :
  • Sec 2.2, final paragraph: "...all WG chairs TCG should make a final check..." - I think the "TCG" here should be removed.
  • Sec 2.4, item 6: Should references here to the "Technical Working Group" and "TWG" be replaced by "Technical Coordination Group" and "TCG"?

The role of the TCG in the review process has been clarified, and all references to TWG have been updated.

• S1.2 Naming convention : BrunoRino
  • TYPE-NAME-DATE.EXT is not currently applied; the name of documents presently in the repository is not prefixed by its type , where TYPE is a code for the document type (NOTE, WD, PR, REC), although it is part of the URL.

Resolution of this issue is pending further inputs from WG/IG chairs.

• Section 1.3 Format : BrunoRino
  • I would advocate making HTML the only mandatory format, for this is the most universally readable format. And suggest PDF as the preferred printable format.

As mentioned above, we require an HTML version and recommend PDF also.

• Section 2 Standards process : BrunoRino
  • I would like to see "Internal Working Draft" added to the list of document labels. This is the stage when the document is under preparation and existent not on the "Documents" area, but on the "Working Group" (twiki) area.

We have reviewed the text and believe that the distinction between a Working Draft that is internal to a WG and a Working Draft that has been published for wider review is now much clearer.

• Section 2.1 Working Draft : BrunoRino
  • For advancing to the next maturity level, it should be asked not only that two interoperable implementations exist, but also some kind of validation service/procedure. for instance, current implementations of SIA and SSA would benefit from such a service.
    • MarkTaylor: this would represent a substantial change to the procedure, but I think it would be an excellent thing and considerably improve the quality of the standards and their implementations.
  • About Implementations : MireilleLouys
    • For testing models, we were talking about "independant" interoperable implementations, which means different teams should implement the specification for a model or a service. The feedback in this case is certainly richer.

We have added the recommendation to include validation tools, though, like two interoperable implementations, this is strongly suggested but not absolutely required.

• Report on interoperability trials: GuyRixon
  • The entrance criteria for PR should include a report on the tests of the proving implementations, either as a separate Note, or as an appendix of the document being progressed. In particular, it is useful to know which, if any features were left untested, and which, if any, requirements were found ambiguous. This was agreed at an exec meeting some years ago but has never been enforced.

We suggest that such interoperability tests be documented as a Note or as text included in the RFC pages.

• Versioning: MatthewGraham
  • The document makes no reference to the versioning of documents or standards. The rule of thumb that seems to be applied is that an integer increment in the version number is required if there is an incompatibility between successive versions of the document/standard. This needs to be clearly stated. Any new version/revision of a (web) service standard will have to have an integer increment since it will be incompatible with previous versions: service request/response messages use namespaces to identify the version, e.g.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope">
  <soapenv:Header>
  <soapenv:Body>
    <PushToVoSpace xmlns="http://www.net.ivoa/xml/VOSpaceContract-v1.0">
...

The namespace on the message body - http://www.net.ivoa/xml/VOSpaceContract-v1.0 - indicates that this is a message to a VOSpace-1.0 compliant service. The same message to a VOSpace 1.1 service would utilise the namespace http://www.net.ivoa/xml/VOSpaceContract-v1.1 instead. A VOSpace-1.0 client cannot be used with a VOSpace-1.1 service and vice versa. So by the rule of thumb VOSpace-1.1 should actually be VOSpace-2.0. The same argument applies, however, to minor changes, e.g. VOSpace-1.13 to VOSpace-1.14.

This brings up another point - how should associated schema, WSDLs, etc., in fact anything with a namespace, be versioned? With the version number of the associated document? For example, the change from v1.13 to v1.14 of a standard just reflects a format change in the WSDL document but this is "new incompatible" version. Should all service standards just employ integer versioning?

These points remain TBA in the context of the naming and numbering conventions.

The above revisions were believed to be sufficiently significant that the Standards and Process Committee has returned the document to a Working Draft. There will be a second RFC period once the document has been republished and promoted to PR.