The TCG companion

This page is intended as an introduction and reference for chairs and vice-chairs of IVOA Working Groups (and to some degree Interest Groups, too). It tries to document and explain common practices within IVOA's Technical Coordination Group. Oh, and: this is non-normative. Feel free to update, extend, and correct the material here.

Standards process

If you are unsure about the various types of documents that the IVOA issues, consult the IVOA document standards; that document explains what all the Note, WD, PR, REC, and PEN, EN business is about.

Reviewing

As a TCG member, you are supposed to review every standard the IVOA issues. IG chairs may chose to ignore that obligation, and there really is nothing wrong with that if the standard is far from your IG's purview. WG chairs, however, must comment and approve (or reject) every Proposed Recommendation and Proposed Endorsed Note. Please take that seriously; it is not nice to leave other WG chairs and document editors waiting for your review for months on end.

Chairs and vice-chairs can split the load of reviews as convenient.

While there is nothing wrong with reviewing other WG's Working Drafts, as a WG chair you really need to have a look at documents when the managing WG calls for RFC. This happens in a mail to the Interop mailing list (see below). When you see one of those, please add an item to your todo list. There is also a list of on-going RFCs on the TCG page. You could add and/or remove documents from your own WG there but: leave the others alone even if you think they shouldn't be there any more and remember to alert TCG coordination about changes (e.g. a document that reaches REC stage is dropped from the table, but has to be reported in the list at the bottom).

It is ok to accompany your review by a github pull request, in particular when fixing typos or similar minor problems.

In your review, you can discuss points not directly related to your WG, although it might be wiser to do that in a separate review in the community section of the RFC page, in particular if you have multiple points to make. Keeping the two categories separate helps people trying to understand the development of the document later.

If you only ask for minor changes, consider casting your approving vote at the bottom of the page right away, perhaps with a brief remark ("pending minor changes").

If you ask for major changes, ideally watch the github repo and wait for a pull request addressing your concerns. If you can read diffs, please make sure the changes actually address your concerns and then cast your vote.

Shepherding documents

As a WG chair, you are supposed to manage document progress on the way to REC or EN for documents produced by your WG. Experienced editors may do much of what is discussed below themselves – if you think they are doing about the right thing, let them, but still keep an eye on what documents your WG issues and make sure there's some basic adherence to procedure – which is there to ensure community participation and consensual development, both of which are good things.

These days, documents are usually being written in ivoaTeX on github. This is documented in the IVOA Note IVOATeXDoc; at least skim over this note so you know what's in there. You or your editors don't absolutely have to use ivoaTeX. But it certainly is a good idea, not the least because that will help later editors; IVOA standards typically have a long life.

Towards a Working Draft

Very early versions of documents live on github exclusively, perhaps using the CI document building, perhaps letting the authors build their own documents. That is called internal Working Draft or iWD. Once you think a sufficient consensus is reached within your working group (i.e., there should have been a post on the mailing list about it and ideally a talk at an Interop), you can upload a Working Draft into the document repository.

To do that, please follow the checklist in IVOATeXDoc – it's easy to get things wrong here in ways that computers just don't or can't notice. Repairing mispublished documents is always a pain.

After posting a WD, notify your WG on the mailing list, and again arrange for a talk/discussion at an Interop.

The RFC

To start an RFC (“Request for Comment” – you can take that literally), prepare a PR (here: proposed recommendation rather than pull request) and upload it to the document respository (using the submission form on the IVOA web or the make upload target in ivoaTeX). Since this is becoming official, be sure to pay close attention to the submission checklist in ivoatexDoc. Then send a message to the TCG notifying it of the freshly uploaded PR. With a bit of luck, someone will already look at it and perhaps find gross technical problems before RFC.

If not, after perhaps two weeks (don't take the times in the Document Standards too seriously here) start the Request for Comments period. To do that, fetch the RFC template and create a new page named <DOCNAME><VERSION>RFC (like VOTable15RFC) based on it. Fill it out and then write a mail to the Interop list. This should include a short explanation what your new standard is about, a link to the PR and the RFC page, and a date by which you would like to have the reviews.

Most of the time, you will not get any responses without politely approaching individual WG chairs, perhaps one whose WG could be particularly interested in the standard at hand. Ask them to do the first review. Having such an icebreaker typically is very helpful.

Then, work with your WG chair colleagues at TCG meetings or perhaps directly by mail. As a guideline, give people at least four weeks; DocStd says the RFC period should be six weeks, and though that has never worked out in reality, it is something like a justification to mail folks after something like this time.

The REC

Once all WGs have signed off on your standard, inform the TCG chairs. When they tell you to (which will mostly take a while because the Exec will have to approve your Standard), change the document status to REC, go through the submission checklist one last time, and then upload.

If your REC uses IVOA identifiers to itself ("ivo://ivoa.net/std/DOCNAME"), you must now update or upload your StandardsRegExt record. See ivoatexDoc if necessary.

Notes

As a WG chair, you generally have no formal involvement with Notes; they are between the authors and the document repository exclusively. However, for notes that claim to “belong” to your WG, have a look and talk to people if you have concerns with what they are writing.

Endorsed Notes

Endorsed Notes work a bit like RECs, except that you go to, if you will, PR directly, which is called PEN with Endorsed Notes. If you (or someone in your WG) plans to go for EN with something, say so at a TCG session or on the TCG list up front. Actual procedures are still somewhat fluid here, so we may need to chat a bit. Don't worry: everyone will be friendly.

TCG meetings

The TCG typically met in person twice a year at the Interops, for a full day in spring and for a half day in autumn. We will probably return to that schedule starting 2023. Otherwise, we have telecons every month or 2, in particular in the run-up to the Interops.

The TCG oversees the RFC and EN processes; it also discusses Errata and VEPs (which are requests to amend vocabularies). All these are tracked on the TCG page. So, before a TCG meeting, please go there and review whether you have an opinion on the items listed there (unless marked frozen). If you think an item is missing, ask at the meeting or on the TCG list.

If nobody from a WG or IG can make it to a TCG meeting, please let the TCG chair (and not the whole TCG list) know.

Interop matters

Before the Interop

At some TCG session before an Interop, you will be asked whether you would like to have a session for your WG/IG. You don't have to have one if you are an IG chair. As a WG, skipping an Interop would probably be a bit odd (or a sign of maturity). Also consider joint sessions where you have a topic with high relevance to two or three WGs/IGs (yes, we had three-WG joint sessions before). Also raising topics for plenary sessions can be useful; propose them quite in advance to help organising the schedule slots.

Once you know you have a session, send around a request for contributions. Have a look at the interop list archives for examples for such calls. There are no strict rules as to the distribution – you can send one message to the interop list (which is several hundred people; avoid sending overly many mails there), or just restrict your circulation to your WG's list. That choice basically depends on how much you expect non-WG folks to want to contribute or whether you want to remind the wider VO public that your WG/IG still is alive and kicking.

We traditionally accept talks more or less until the last moment. Giving a date until which people should hand in contribution is still a good idea, because that way you have a good chance to get contributions before that last moment and have a presentable programme a bit in advance of the conference. Pay also attention to keep room for discussion, not simply squeezing lots of small talks, in the end Interops are meant more for discussion than showcasing.

At some point, the TCG chair will send around a draft interop programme residing on the twiki. You have to fill out your WG's session programme yourself. Everyone bases that on their WG's programme of the previous Interop; make sure you don't forget to update place and time. Announcing that programme on the WG list gives people a last chance to consider whether they have something to say.

During the Interop

On the opening day of the interop, prepare and upload opening slides, which should include a few words on your WG's purview (for newcomers), look back at what your WG has been up to since the last Interop (use the Roadmap and comment if there are major deviations from it), and say a few words on what will happen in your session(s) – or comment why you don't need a session. Try really hard to keep all this below five minutes, because these Charge-to-the-WG sessions tend to overrun their allotted time.

At your session, you will typically chair it and perhaps give a talk of two – this is another example for why it's useful that there is both a chair and a vice chair.

After the session, make sure everyone has uploaded their slides and bug them if they have not. Consider whether you should add brief minutes to your session page. While it probably is not terribly important to document what was said in the talks – there are the slides, after all –, giving a short account of the discussions is probably useful in most cases.

After the interop

After the interop, the TCG chair will send around a reminder to fill in your Roadmap contribution and usually seed it with your previous semester's roadmap. Update this while your memories of what happened during the Interop are still fresh.

Consider scheduling “running meetings“, i.e., telecons between the Interops, in particular if you had to cut short an important discussion in the session.

Github considerations

If all works well, when you start as WG chair, you should become a member of the corresponding group on github, which in turn should immediately give you administration privileges on your WG's standards. It is then up to you to pass out write privileges to document editor(s) as appropriate.

For the time being, when you have problems managing your WG's documents, you will reach the owners of the ivoa and ivoa-std organisations on the stdproc mailing list.