TWiki> IVOA Web>DocStdRFC (revision 10)EditAttach

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

Find an example to guide you on how to add comments

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

  • 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.
    • BrunoRino: I support (both).

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

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

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

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

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

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

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

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

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



Edit | Attach | Watch | Print version | History: r14 | r12 < r11 < r10 < r9 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r10 - 2008-10-10 - MireilleLouys
 
This site is powered by the TWiki collaboration platform Powered by Perl This site is powered by the TWiki collaboration platformCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback