Node manager text and language review #120
Conversation
Updates text, main issue text changes
Updating Gitlab terminology and highlighting points for depper review before merging
Ran through and cleaned out /issue/ terminology where needed, things still to do is check if there is any new adds we want, cross check the templates with Dan's reworked clean up and check if training operates in same manner as current processes (this will be as required in the coming month(s) leading to push in Jun and post.
|
is this waiting for review from someone? wanna make sure we un-stick it if its stuck :P or merge if its its ready! |
Added more contextual text and updated the template examples given
| 5. Data request report is compiled and provided to requester, once all permissions have been received. | ||
| 1. As OTN registered projects are public and open by default, check if the data requested is available publically for sharing. | ||
| 2. Request for data (from person other than data owner) submitted | ||
| 3. Data request is scoped, in a GitLab Ticket. All details from requester is included. |
There was a problem hiding this comment.
This first sentence doesn't need a comma.
There was a problem hiding this comment.
Also, either 'all detail from requester is included' or 'all details from requester are included'.
| 1. As OTN registered projects are public and open by default, check if the data requested is available publically for sharing. | ||
| 2. Request for data (from person other than data owner) submitted | ||
| 3. Data request is scoped, in a GitLab Ticket. All details from requester is included. | ||
| 4. Impacted PIs are identified, and contacted, seeking written permission for requester to access the information. |
There was a problem hiding this comment.
"identified and contacted to provide written permission...".
| 2. Request for data (from person other than data owner) submitted | ||
| 3. Data request is scoped, in a GitLab Ticket. All details from requester is included. | ||
| 4. Impacted PIs are identified, and contacted, seeking written permission for requester to access the information. | ||
| 5. Written permission is documented in GitLab Ticket, to preserve the paper-trail. |
| 3. Data request is scoped, in a GitLab Ticket. All details from requester is included. | ||
| 4. Impacted PIs are identified, and contacted, seeking written permission for requester to access the information. | ||
| 5. Written permission is documented in GitLab Ticket, to preserve the paper-trail. | ||
| 6. Data request report is compiled and provided to requester, once all permissions have been received. |
| - Tracker projects only submit data about tag releases and animals. They get tables based on the tags, animals, and detections of those tags. | ||
| - Deployment projects only submit data about receivers and their collected data. These projects get tables related to receiver deployments and detections on their receivers. | ||
| - Data projects are projects that deploy both tags and receivers and will submit data related tags, animals, receivers, and detections and will get all the related tables. | ||
| When loading the project metadata using the Create and Update projects.ipynb (shown in subsequent training materials: 07_project_metatdata.md) the data loader will select one of the above. |
There was a problem hiding this comment.
The words 'subsequent training materials' should link to the episode 07 page.
| -> Checking the researcher names, affiliations and emails are listed row wise per researcher and a data repository role has been chosen. | ||
| -> Obvious spelling errors. | ||
| -> Empty sections where no information has been provided | ||
| -> Non-english text characters, these are flagged by the nodebook but catching them visually allows for estimating time required to load project metadata. Non-english text characters are flagged as the database cannot store them readily so time is required to parse them. If an error is received when loading project metadata and a unicode character code is given such as U+00E1, you can google this and find what it is and visually scan or find and replace the metadata text for them. |
There was a problem hiding this comment.
Comma should be a period.
| Even though `tag`, `deployment`, and `detections` data all have their own loading tools and processes, their general path through the database is the same. | ||
| - Their data workflows all begin with a submission of data or metadata files from a researcher. | ||
| - The Node Manager ensures there is a copy of the file on the Node's document management website. | ||
| - The Node Manager ensures there is a copy of the file on the Node's document management website, this is typically the Plone members repository but is decided in the creation of the node what this managment website will be. |
There was a problem hiding this comment.
Comma should be a period.
| objectives: | ||
| - "Understand the data-loading workflow" | ||
| - "Understand how to create and use GitLab Issues" | ||
| - "Understand how to create and use GitLab Work Items" |
There was a problem hiding this comment.
Episode 3 refers to 'Ticket' rather than 'Issue' or 'Work Item', we should standardize the language across the lessons.
| Data Managers receive data from a researcher and then begin the process of QA/QC and data matching: | ||
|
|
||
| 1. Records are received and a GitLab Issue is created. | ||
| 1. Records are received and a GitLab Ticket is created. |
| The FACT Network currently uses a custom instance of Research Workspace for the same purpose. | ||
|
|
||
| The ACT and GLATOS Networks use a custom data-submission form managed through their networks' web sites. | ||
| The GLATOS Network use a custom data-submission form managed through their networks' web sites. |
There was a problem hiding this comment.
"... GLATOS Network uses..."
| # Documenting data submission | ||
|
|
||
| *NOTE: GitLab Work items are often referred to as "tickets" and "issue(s)", gitlab now uses work items and issues interchangably to refer to tickets. Work items is the prominent language used on the Gitlab website. Here we will generally use the term tickets with the exception of cases where we direct the user on using gitlab features.* | ||
|
|
There was a problem hiding this comment.
Oh, OK, I was commenting as I went here. I disagree with this. I think it's OK to note that in casual speech we might use 'ticket' or 'issue' interchangeably with 'work item' since that language is newer and not as entrenched, but for actual documentation we should probably stick 1:1 with what's on Gitlab. Either that or we should put this note a lot earlier, before we start talking about tickets/issues/work items. I defer to the DACs, though.
There was a problem hiding this comment.
Personally I don't think there's a problem with interchangeable terms. Gitlab replaced "issues" with "work items", which have 3 subtypes - "incident", "issue", and "task". I don't think it's necessary to get into the weeds on this.
I definitely agree, though, that this could be closer to the top.
e: on thinking about it, if we dropped any term it should be "ticket", which never appears in gitlab afaik
| At this time we will take a moment to practice making GitLab Work Items, and explore other pages on our GitLab like, `Milestones`, `Repository`, `Snippets`, and `Wiki`. | ||
| - Milestones can be found under the Plan heading in the left-hand side of the Gitlab page when within your Node-DAQ gitlab section. Reviewing this page can give insight into the progression of ticket processing from unstarted, ongoing to completed. | ||
| - Repository is found under the Code heading in the left-hand side of the Gitlab page also. This page shows the files associated in the Gitlab such as templates (click .gitlab folder in upper left unter Files heading, then issue_templates). | ||
| -Snippets is found under the same Code heading, this a good place to store copy and pasteable email templates for repeated queries to researchers or responses for frequently asked questions. You can also store bits of code here and there such as SQL queries for the Node database for common database searches |
There was a problem hiding this comment.
Space after the hyphen.
| This will be relevant for users of the `Database Fix` suite of Nodebooks only. If you are not going to use these tools, you can skip this cell in the Nodebooks. | ||
|
|
||
| A Gitlab Access Token will allow Nodebooks to access your GitLab account and insert comments into an Issue directly, as you are working on it. This has been developed for the Database Fix Notebooks to ensure all changes made within the notebooks are documented in GitLab properly. The automation is part of the `OTNGitlabAutomation` package. | ||
| A Gitlab Access Token will allow Nodebooks to access your GitLab account and insert comments into an ticket directly, as you are working on it. This has been developed for the Database Fix Notebooks to ensure all changes made within the notebooks are documented in GitLab properly. The automation is part of the `OTNGitlabAutomation` package. |
There was a problem hiding this comment.
"insert comments into a ticket"
jackVanish
left a comment
jackVanish
left a comment
There was a problem hiding this comment.
Ticked out all the typos I noticed. I can't speak to the content so I defer to the DACs on that. The only thing I can mention on that front is that I find the switching between 'ticket' and 'work item' kind of disorienting- should we stick to one for an instructional course? I assume the DACs have already been in discussion about this, though, so again I defer if those conversations have already been had.
| 2. If any of the above mandatory fields are blank, follow-up with the researcher will be required if: | ||
| * you cannot discern the values yourself. | ||
| * you do not have access to the Tag or Receiver Specifications from the manufacturer (relevant for the columns containing transmitter information). | ||
| * you do not have access to the Tag or Receiver Specifications from the manufacturer, these can be checked in DBeaver (relevant for the columns containing transmitter information). |
There was a problem hiding this comment.
Comma should be a period.
| Please make sure of the following: | ||
|
|
||
| 1. Is the PI-provided collection code unique/appropriate? Do you need to create one yourself? Existing schemas/collection codes can be seen in the database. | ||
| 1. Is the PI-provided collection code unique/appropriate? Do you need to create one yourself? Existing schemas/collection codes can be seen and checked for prexistence in the database. |
There was a problem hiding this comment.
"preexistence" or "pre-existence"
|
|
||
| 1. Node: select your node | ||
| 1. Collaboration Type: based on the abstract, are they deploying only tags (`Tracker` project), only receivers (`Deployment` project) or both tags and receivers (`Data` project)? | ||
| 1. Collaboration Type: make an assessment based on the abstract, are they deploying only tags (`Tracker` project), only receivers (`Deployment` project) or both tags and receivers (`Data` project)? |
There was a problem hiding this comment.
Comma should probably be a colon or period.
| # Documenting data submission | ||
|
|
||
| *NOTE: GitLab Work items are often referred to as "tickets" and "issue(s)", gitlab now uses work items and issues interchangably to refer to tickets. Work items is the prominent language used on the Gitlab website. Here we will generally use the term tickets with the exception of cases where we direct the user on using gitlab features.* | ||
|
|
There was a problem hiding this comment.
Personally I don't think there's a problem with interchangeable terms. Gitlab replaced "issues" with "work items", which have 3 subtypes - "incident", "issue", and "task". I don't think it's necessary to get into the weeds on this.
I definitely agree, though, that this could be closer to the top.
e: on thinking about it, if we dropped any term it should be "ticket", which never appears in gitlab afaik
| Here is the Issue checklist, for reference: | ||
| Immediately upon receipt of the metadata, you must create a new Gitlab Ticket (aka Work Item). Please use the `Project Metadata` work item checklist template found in the drop down menu under the 'Description'. | ||
|
|
||
| Here is the Work item checklist, for reference: |
There was a problem hiding this comment.
Just a note that this is likely to change soon (next few weeks?)
|
|
||
| Using these fields, the `detections-create detection extracts` Nodebook can determine which extracts need to be created for each push. | ||
|
|
||
| <!-- Do we still need this? MG to PERSON Y/N --> |
There was a problem hiding this comment.
You can remove "As of December 2024".
I think it's still good to let people know they should be on main or integration
Showing off how to commit changes from GitHub rather than locally.
4 participants
Mostly updating usage of gitlab issue to gitab ticket, in general reference to ticketing process and specific new terms introduced like work items where appropriate. Added explanatory text for user early on to clarify to end user of materials.