(r12) RFCDocStdV2 < IVOA

IVOA Web>IvoaStdsDocsProc>RFCDocStdV2 (revision 12) (raw view)~~EditAttach~~
---++ 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.

Latest version of IVOA Standards Document can be found at: [[http://www.ivoa.net/documents/DocStd/20160923]]

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

%RED% The community, including the TCG members, is invited to provide comments before Trieste Interop meeting (21 October 2016). %ENDCOLOR%

---+++ TCG Vote: 6 November 2016 - 20 November 2016

---
---

---++ 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 TWiki.WikiName 
      * Response (by TWiki.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:

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

-- or we just refer to sect. 2, which essentially has it all as well.

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

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

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

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

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

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

(8) p. 5 "In formation" -&gt; "Information"

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

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

(10) In 1.6, &lt;ConciseName&gt;-&lt;currentversion&gt; should be written &lt;ConciseName&gt;-&lt;CurrentVersion&gt; for consistency.

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

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

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

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

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

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

(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

<blockquote>"The WG chair may issue additional document versions in order to reach a consensus."</blockquote>

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

(18) In Sect. 3, "Process", should make clear how the TCG decides. I'd hence propose to change the enumeration to:

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

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.

-- IVOA.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 ? -- IVOA.DaveMorris - 2016-09-29
-- 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.
   * 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.
   * 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.
   * 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.
   * 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?
   * 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.
-- IVOA.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 "<em>It is a Note expressing suggestions from and opinions of the editor</em>".
   * p5 - 1.3 Format. "<em>ivoatex+volute</em>" 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 ?...)
   * p6 - 1.6 Errata - It is surprising to have this Errata section before the standards process.
   * p6 - 1.6 Errata. - A lot of unecessary line feed in this paragraph.
   * 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).
   * p9 - point 4 "<em>validation tools should be available</em>" - 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 ?
   * p12 - Endorsed Notes process - "<em>a lighter weight review process than the one undergone by the IVOA Recommendations...</em>" 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.
   * p15 - Appendix - "<em>This document is been produced by [...]</em>" - the "..." should be replaced by TCG ?
-- IVOA.PierreFernique - 2017-03-20

   * p5 - 1.3 Format. Typo: "In formation" should be "Information".
   * 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.
      * p8 - "IVOA's mission" and related footnote. http://www.ivoa.net/pub/info/index.html is "Not Found"
-- IVOA.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 ?

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

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

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

-- IVOA.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.
   * Endorsed Notes track documents: Not necessary to spécify the "Endorsed Note may refer to a REC". Any document may refer to a REC.
-- 1.2 Naming and version numbering conventions
   * The sentence "(..., bit this should not be a major problem) can be removed
   * html, pdf, doc... are not Mime types but filename extensions
   * Misalignement in the table of examples
   * Could be nice to specify that changing the version number requires a new REC process
-- 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..)
-- 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
-- IVOA.LaurentMichel - 2016-10-26
---+++ 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.

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

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

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

-- IVOA.MarkusDemleitner - 2016-10-13
---+++ Semantics Working Group ( _Mireille Louys, Alberto Accomazzi_ )

---+++ 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_ )

---

<br /> <!--
      * Set ALLOWTOPICRENAME = IVOA.TWikiAdminGroup
-->
Topic revision: r12 - 2017-03-20 - TomDonaldson
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
Time Domain
Committees
Stds&Procs
www.ivoa.net
Documents
Events
Members
XML Schema