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

• "Adding" comments : by BrunoRino : I want to "add" a comment here. How do I do it?
  • BrunoRino: See above.

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

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

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

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

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

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