(r8) DocStdRFC < IVOA

IVOA Web>DocStdRFC (revision 8) (raw view)~~EditAttach~~
---++  IVOA Document Standards RFC

This document will act as *RFC* centre for the [[http://www.ivoa.net/Documents/cover/DocStd-20080915.html][ IVOA Document Standards 1.10 Proposed Recommendation]].

Review period: 16 September 2008 to 15 October 2008
<!-- Tcg evaluation:  -->

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 TWiki.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? 
      * 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.
      * 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, <i>Definition of the Flexible Image Transport System</i>, 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?)
         * BrunoRino : The current practice is a link to the RFC page on the document table (http://www.ivoa.net/Documents/)

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

------









<br/>
<!--
      * Set ALLOWTOPICRENAME = %MAINWEB%.TWikiAdminGroup
-->
Topic revision: r8 - 2008-10-06 - PaulHarrison
IVOA
Log in or Register
IVOA.net
Wiki Home
WebChanges
WebTopicList
WebStatistics
Twiki Meta & Help
IVOA
Know
Main
Sandbox
TWiki
TWiki intro
TWiki tutorial
User registration
Notify me
Working Groups
Interest Groups
Committees
Stds&Procs
www.ivoa.net
Documents
Events
Members
XML Schema