DocStd-2_0-Next < IVOA

IVOA Web>IvoaStdsDocsProc>DocStd-2_0-Next (2025-04-29, MarcoMolinaro) (raw view)

---+ IVOA Document Standards v.2.0 - Next

This page reports the ongoing efforts for a revision of [[https://www.ivoa.net/Documents/DocStd/20170517/index.html][REC-DocStd-2.0]].

---++ (vconf) 28 April 2025 - 16:00 UTC

An online meeting was held to start the process. Here follows a _copy/paste_ of the etherpad notes taken during it (the etherpad should be [[https://yopad.eu/p/ivoa-docstd-restart-365days][here]] up to April '26).

(participants: Marco, Markus, Pat, Tom)

Pat has a June 2020 draft of DocStd prepared by Christophe and Françoise.  There are also notes from the Bologna Interop.  But perhaps we should start with 2.0?  Probably...  Pat will check the changelog.

   * Errata process and scope
      * Can we work in the errata into modern documents?  
      * If so, would the document date change?  
      * How would that go to ADS?  
      * Does the changelog change?
      * We should probably have an extra changelog with the erratum, and we should have some markup that shows the change in place.

   * Micro-revisions

This could be for Errata, but also possibly small editorial changes, e.g., in VOTable 1.5 there was a premature REC that received a few changes after approval, but we feel these weird cases shouldn't influence our process.  For Errata, leaving some "patchlevel n" marker in the version string: "REC 1.0a", "REC 1.0b"?  But then the micro version in semantic versioning kind of is about patch levels in the end.

   * RFC: how to improve

Can we streamline the process?  MD wouldn't want the WG chairs off the hook because his RFCs actually improved his documents.  And since they are volunteers, there is probably little we can fix in the process.

However, the system with all comments on one wiki page and little tracking of where something got fix.  Perhaps (and MD hates saying this) WG reviews should be github issues? After all, we're already sold to github hair and hide.

Oh, and if there's differences between DocStd and our practice, we should fix DocStd.

Can we do something about the vicious circle that people only want to implement against REC-s, but things can only become REC-s if there are implementations?

   * Use case endorsing/approving w.r.t. model (or other) RECs

Mark CD has been asking for a while what would make up a reference implementation for a DM, because usually they only use a small portion of their models.  MD happens to think that if you don't use it you don't specify it.  TD argues that people tend to put in extra feature to future-proof their standard given the sluggish standards process.

   * Source porting: doc to ivoatex 
      * MD volunteers

   * Impacts (and desiderata?) on docrepo reconstruction

Postponed until someone resumes work on the new docrepo.

   * Document track: REC to EN?

Should DocStd be an EN rather than a REC?  MD would advise against it because making a REC from an EN has been ugly for the UCD list, and there is little organisational advantage.  MM argues that DocStd really isn't a technical specification, but doesn't feel strongly about it either.

But then: Does the VO have a constitution or something where the structural aspects of it are covered?

   * Editorial issues
      * author/editorship: minor since changes might be major
      * MM dislikes the sketch of process
      * Should vocabularies be referenced from DocStd?

<br />
<!--
      * Set ALLOWTOPICRENAME = IVOA.TWikiAdminGroup
-->

Topic revision: r1 - 2025-04-29 - MarcoMolinaro

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