Remaining steps to complete revision of Review Manager guidelines

[baskaufs]

As noted by @gkampmeier in #2 (comment), the @tdwg/exec at their 9 Feb 2021 meeting requested a group of former review managers including @baskaufs @gkampmeier @Tasilee and @dagendresen to undertake revisions of the "Guidelines for Review Managers for Proposed TDWG Standards", originally writtin 15 May 2009 by Lee Belbin.

With the merge of #11, these revisions are largely complete. The following steps still need to be taken in order to complete this task:

• Obtain final edits from @stanblum (refer to Overhaul Review Manager Guidelines #2 (comment))
• Obtain any necessary feedback from @tdwg/exec and revise the draft as necessary.
• Complete YAML header section (Lines 2-8) with necessary cover images, tags, etc. or delete lines if unnecessary
• Determine where the page will live on the TDWG website and place the URL in the Bibliographic citation (line 23). I would also recommend linking to this document from the header of the Process page.
• When all else is completed, fill in the "Date version issued" (line 13)
• Move the page to the appropriate spot on the website and publish.
• Inform the Executive Committee that the task has been completed and close this issue.

[baskaufs]

One thing I was considering when looking at the header section was whether we should list our ORCIDs as text and hyperlink that rather than just including them linked to our names. I'm in favor of encouraging as many people as possible to get and use ORCIDs, so having them easily visible might help incentivize others to do the same.

[gkampmeier]

I see the value in that. What I had actually hoped for was the little ORCID icon, but getting any graphics into our website means adding it to the static server (@stanblum has access) and the html provided by ORCID for embedding on a webpage seemed excessive

(although it renders well here, apparently), so maybe it's no biggie.

https://orcid.org/0000-0002-5178-4170

oops, but the icon didn't appear after all that 👎

[gkampmeier]

@baskaufs The other issue we didn't deal with was defining "Author." I'm wondering if the easiest way to deal with that is to put Author as 1.1 under responsibilities (as it begins there, moves to the Exec, who then assigns a Review Manager, who finds Independent Reviewers and to do away with much of 2 or reword it so it is more an explanation of the TDWG Standards Track and less a list of responsibilities of the Review Manager (which should be part of 1 Responsibilities.)

[baskaufs]

Oh, yes, I forgot about that. Sorry! If you have an idea of how to fix it, please go ahead if you have time.

As far as the embedded HTML goes, I think it should be not problem to stick it in the page. As long as it's going to get rendered as part of the website, it should work fine. I've embedded a lot of iFrames in pages that get rendered as GitHub pages and it hasn't been a problem to just stick it in the middle of the Markdown. I can run a test elsewhere if we want to see how it looks.

[baskaufs]

@gkampmeier I just tried the HTML snippet on this page. When first I pasted all the code, it displayed the <div> tag, so I had to put the name inside the div and then it worked. If you think it looks OK, I can edit the names and ORCIDs to use this code.

[gkampmeier]

@baskaufs it does look good. I'm going to give the Authors thing a go--you might want to wait until I do that rearranging in a new branch (I'm assuming this is the path I should choose for something so major).

[baskaufs]

Sounds good! You are a GitHub pro now!

[baskaufs]

OK, I will go ahead and try to do the ORCID HTML.

[baskaufs]

Alright, I think I have the ORCID widgets working now. The ultimate test will be to see how it looks when its actually rendered on the website. If there is something wrong with it there, we can always go back and have another go at fixing it.

It's interesting that the widget code appears to include schema.org metadata. I think that at least in theory a crawler like Google would be able to pick it up and make a connection between this page and the contributors as entities described in ORCID. I'm dubious that anything useful actually comes from this at present, but at least there is potential using this method to make a semantic link between the page and someone's ORCID profile. Interesting...

[baskaufs]

Unless we're missing something, I think perhaps this is just waiting for @stanblum to add whatever he had in mind and then it would be ready for the Exec to look at.

[baskaufs]

Aaaaak! Where did your revisions go, Gail?! I must have done something bad. Let me look in the revision history to fix it!

[baskaufs]

OK, phew. The good thing about Git is that you never actually lose anything. The bad thing is that you can mess things up if you don't follow the workflow. I was editing locally on an old copy and didn't update it after the pull request was merged. I did the update, but then replaced the whole document with my work instead of just the part of the text I'd edited. Sloppy...

Anyway, I think I fixed it. Everything looks OK now.

[gkampmeier]

@stanblum @baskaufs It occurs to me that we have left off steps for the 1.2 TDWG Exec--it is not enough to say that they ratify the new standard (and shouldn't this have a time period attached?), don't they then have next steps in notifying the RM and Author of the success (within a certain time period) as well as directing the posting of the new standard on the website and having the news distributed through XX outlets (some of this may be for the TDWG Secretary/Secretariat; some through Outreach & Communications)?? How granular do we make this? I think something needs to be added as this is a place where the ball has been dropped in the past.

[baskaufs]

@gkampmeier Well, these are important points. I think the question here is one of scope. This document is described as a guide for review managers, not a guide for the executive, nor an amendment of the process document. I was looking at the process document and its "Ratification of standards" is silent about the details of the final Executive approval, other than to say "A specification must have been through at least one round of public review before the Executive Committee may accept it as a Standard", implying (along with the figure) that the Executive gives the final approval for ratification.

In contrast, Section 3.3.3 of the VMS is very clear that the Executive must render a decision in 30 days (assuming that "must" means "shall"). However, the scope of the VMS is restricted in two ways: it applies only to existing standards and it only applies to standards that define vocabularies. It is actually week in that it doesn't exactly define what a vocabulary is. DwC and AC are clearly vocabularies, but it's a bit unclear whether an XML schema-based standard like ABCD is a vocabulary. (I think it is, but that's an opinion given that "vocabulary" hasn't been defined.)

I agree that the ball has been dropped in the past. I'm just not sure this is the place to fix it. As the document is currently described, it's an informative document that isn't part of any standard and doesn't carry any force. It basically reflects official policies defined elsewhere. If the Exec has policies about time limits, notifications, etc. we should put them here. But we can't really make those policies.

I feel like the TDWG Process document has some serious deficiencies. In particular, it lacks any requirement for carrying out and reporting the results of testing of technical specifications. This is a huge hole -- none of our aspirational peers (IETF, W3C) lack such a requirement. The VMS includes something like that in Section 4.2, but as I noted, its scope is limited and doesn't include new standards. As we discussed earlier, the mechanism for updating the Process document is unclear. It's self-described as TDWG's "by-laws", so I guess Article 9 of the constitution would apply:

The Executive Committee may propose that by-laws be established, altered, or repealed. The by-laws proposal must be published and the membership notified at least thirty days before the close of voting. To be adopted, the proposal must receive simple majorities of affirmative votes from both individual and institutional members.

[gkampmeier]

@baskaufs thanks for these clarifications. I certainly held no illusions that adding points to the TDWG Exec's responsibilities would fix anything, but it might (if such boundaries existed) at least provide another reminder and a way for the Review Manager to follow up on all of the work already accomplished if announcement of ratification and placement on the website had not yet happened within an expected time. I figured you and @stanblum might have a better handle on the mechanics of this than I.

[baskaufs]

Well, let's see what @stanblum thinks. It would not be bad for the R.M. to have a list of things to follow up on. But given that there isn't any official deadline for the Exec to respond, I suppose it should be made clear that 30 days would be a reasonable time to expect a response, vs. a requirement.

[baskaufs]

@Tasilee @gkampmeier @dagendresen Can you all take a look at this letter of transmittal and edit/proofread as necessary? Or if you have nothing to add, give this comment a thumbs up. When it's finished, I think we can send this to the Exec for review (the next step).

[gkampmeier]

Corrected a typo, but otherwise is a beautiful thing Obi-Wan.

[Tasilee]

Thanks @baskaufs and @gkampmeier: I couldn’t have done better.

[baskaufs]

Alright, I will go ahead and ping the Exec to take a look at what we've done. Thanks, all!

[debpaul]

I suppose it should be made clear that 30 days would be a reasonable time to expect a response, vs. a requirement.

This makes sense to me for now @baskaufs

[baskaufs]

Alright, I added a sentence about expecting a response from the Executive in 30 days. If there isn't any guidance on COIs to reference, then we are done. I'm going to check the next box.

[baskaufs]

@stanblum @gkampmeier I guess you are the masterminds about the TDWG website. Where should the finished document go? I think there should be a link on the about page; perhaps in this paragraph as a text link?

TDWG standards are developed by interest groups. The process for establishing interest groups and ratifying standards is described in the TDWG Process. More recently, TDWG has adopted another specification to guide the incremental maintenance of vocabulary standards.

Optionally, it could be added as "brick" at the top of that page, but is this too much of a niche document for that? The one thing that might argue for it is that this is probably the clearest description of what actually happens to a standard during a public review. So in that sense, it's not just for review managers, but also for Task Groups, the Exec, potential Review Managers, potential reviewers, or anyone who needs to know what's going to happen during the review process, or anyone who wants to understand better what their role is in that process.

We also need to decide about what kind of header the page should have when it's on the website. I'm clueless about web design and find those details irritating, so it would be best if someone else just fixes the YAML header on the doc in a suitable way and we can tick that box as well.

[gkampmeier]

@baskaufs I can lose hours in searching for the right photo for web pages :) Unsplash.com is our go-to for header images as they have freely available licenses for reuse of high quality photos. I suggest https://unsplash.com/photos/D18ZnjlhVqM as the right mix of curiosity (knowing squirrels), landscape presentation and subject slice (we have no ability to adjust where the slice occurs on the photo), and biodiversity interest for the page header.

The placement of the new guideline on the website is a bit more tricky, or maybe we should just be worried about where its home should be. Theoretically it would be under TDWG Process, which is nestled under the About tab, because of the detailing of Ratification of standards. It appears also to be the primary page that mentions a generic (rather than specific people as) Review Manager as a position in a search for the term on our website.

I agree, however, that it needs greater visibility, but I'm not sure that it is appropriate to add a tile ("brick"?) to the About page. I suggest expanding the opening paragraph on the Standards tab to link to the TDWG Process

TDWG standards have a status and category. Our standards are also available as a collection on FAIRsharing, which places them in context with databases that implement them and data policies that endorse their use.

Consider inserting after the first sentence:

Current standards and those under consideration as Draft standards are governed by the TDWG Process, which includes the appointment of a Review Manager (url) to oversee expert and public review of TDWG standards.

Arguably links should also exist under the Community tab. Probably the best place to add something about the review manager there is adding to the second sentence and modifying the subsequent sentence:

The TDWG Process describes the steps for establishing and maintaining interest and task groups. Most important among these is to write the group’s charter and have it reviewed by the TDWG Executive Committee...

Consider the following changes in italics:

The TDWG Process describes the steps for establishing and maintaining interest and task groups as well as the process for ratification of standards under the guidance of a Review Manager (url). Most important among these for new interest or task groups, is the guidance for writing the group's charter and steps for having it reviewed by the TDWG Executive Committee.

@stanblum are there places that I've missed, aside from also announcing this addition as a news item? Should a section about the ratification be added at the end to Standards Status and Categories?

[stanblum]

I'm looking at all the places where we can reference this doc. It is relevant to anyone working on a specification that needs to be reviewed, so I think it's appropriate to reference it from the Community home page. I think the first paragraph on the Community page will need to get broken into three, but that's an important place to reference this doc. The main Process (Bylaws) doc also needs to include a reference to the review manager. Maybe just a link where "review manager" is mentioned. I'll look into that.

I think the Review Manger guidelines should live under the About section where all the other structure and process docs live. More specifically, if the doc is placed directly under the About menu item (directory), it will get its own badge (square box at the bottom of the page, in the order given as "page_order"). If it's placed under "The Process" directory, it will show up at the bottom of that page. Given its broader relevance, I would be inclined not to bury it under The Process.

RE the header image: for now, let's use the image that @gkampmeier suggested. (Herding cats might be a more appropriate metaphor, but I don't there are any photos of that.) That can always be changed if anyone finds a more representative image.

So.... I'm going to go forward with posting this. Changes can always be made later. :-)

[stanblum]

By the way, I thought I added at least minimal text on the conflict of interest issue. There are some thoughts about the issue under 1.2 and 1.4. Someone else might have added those, I don't remember -- I just have a vague recollection of writing some text in email, a GoogleDoc, or maybe directly to this doc.

[stanblum]

@baskaufs: should the "Date version issued" be changed to the date this actually gets posted on the website?

[baskaufs]

@stanblum Yes, you had added some COA text. The question was whether there was some external definition of what exactly constituted a COA. We decided that was out of scope for us to worry about. But your COA edits got incorporated.

And yes, just change the date to 2021-11-22. The bibliographic citation section also needs to be edited to have the URL of where it's going to live. I think those are all included in the checkboxes at the top of this issue.

[stanblum]

I've done those things, also some formatting and slight editing. It's posted (status: hidden) here: https://www.tdwg.org/about/review-managers/

Do you want contributors on separate lines or all in a run-on block?

[baskaufs]

Opinion, @gkampmeier ?

[gkampmeier]

@stanblum @baskaufs I think visually they would be better on separate lines given that ORCIDs are so long. I thought @baskaufs you had figured out the code to attach the ORCIDs to their icons...? Then they'd be OK as run-ons in a block

[stanblum]

I've inserted line breaks after the contributors. We can continue to tweak formatting as required. I'm going to change the status to published.

Closing this issue with all tasks completed.

[gkampmeier]

Implemented wording changes to Standards and Community tabs outlined 12 h earlier to include references to the Review Manager documentation.

[baskaufs]

@gkampmeier Yes, I thought I'd figured out how to do the icons. I guess if we want to fix that, we could change it later.

[baskaufs]

This is done and published on the TDWG website