Review and improve metadata tooltips, field labels and watermarks

[TaniaSchlatter]

This issue is to outline and track the effort to improve tooltips, field labels and watermarks related to metadata blocks. Clear and consistent tip text, labels and watermarks should help depositors curate their datasets and enter data accurately, leading to more and more consistent metadata.

Goals:

• Improve the collection of dataset metadata
• Define and document rules for adding or editing metadata tip text, field labels and watermarks

Scope/definition of done: Review metadata tooltip text, field labels and watermarks for consistency and clarity: citation block, social sciences block, journals, geospatial, astrophysics

• [x] define "working rules" to guide grammar and style/consistency improvements to tip text, form labels and watermark text
• [x] apply the working rules to existing tooltips, field labels and watermarks. Drafting proposed edits for review
• [x] document opportunities for additional improvements, such as form layout and behavior. These could be broken off as separate issues
• [x] review proposed text changes with metadata/topic experts
• [x] communicate with the community about changes (affects languages/translation)
• [x] update tooltip text, field labels and watermarks in Dataverse
• [x] evaluate changes
• [ ] complete & share the style guide

[jggautier]

We're recommending removing some tooltips. I tested if removing certain tooltips from the UI would be as easy as just removing the text in the description columns of a metadatablock's TSV file, like in the citation.tsv file:

To test this, I created a fork, edited the citation.tsv file to remove some text in the description column that's used for the tooltips, and spun up the fork in an AWS instance. The tooltips I had tried to remove were still there, using the text that's in the latest version of the citation.tsv file.

So I'm writing this to say that we might want to get a sense of how much development work would be needed to make sure that the tooltips we determine should be removed can be removed.

[djbrooke]

@jggautier feel free to pop in #dv-tech if you want to talk through anything from the technical side.

[djbrooke]

Thanks @TaniaSchlatter @scolapasta @jggautier for discussing earlier. The above checklist remains accurate.

• @scolapasta @jggautier and @djbrooke will meet to get a shared understanding of how tool tips are managed and updated for those installations that have localized and those that have not. In the meeting, we should also look at how to manage tool tips for system generated content (such as the dataset PID). We're planning on meeting Thursday at 1 PM.
• Groups that were mentioned for follow up were DDI Alliance, Scholar's Portal/Portage, and the curation team at the Harvard Dataverse Repository. @jggautier has a list as well. We will do targeted outreach to these groups and also general outreach to the community.

[jggautier]

I think most of the edits to the titles, tooltips and watermarks of fields in the citation metadatablock can be made by editing and reloading the citation.tsv file and citation.properties file. I've been making those changes in a branch at https://github.com/IQSS/dataverse/tree/8127-citation-field-improvements and I'm able to update that branch with those types of changes.

The changes that we agree should be made for this GitHub issue but can't be made by editing and reloading the citation.tsv file and citation.properties file are:

• Editing the title (what's shown in the UI) for the "Dataset Persistent ID" field
• Editing the description/tooltip for the "Dataset Persistent ID" field
• Editing the description/tooltip for the "Publication Date" field

Can those three things be changed easily?

The "working rules" to guide grammar and style/consistency are shaping up, too. I think they should be made publicly available, but when and how are open questions.

There are other changes we felt would be improvements but that we decided not to make for this first round of improvements because they would involve a level of design and development work that would hold up the majority of the other improvements. We'll be opening other GitHub issues about those.

[scolapasta]

@jggautier I would expect those changes to just have to be made to the bundle.

[jggautier]

Ah okay, thanks. I think I see where in the Bundle.properties file (https://github.com/IQSS/dataverse/blob/develop/src/main/java/propertyFiles/Bundle.properties). I'll give it a try.

[jggautier]

That worked, thanks!

[jggautier]

Tooltips aren't being removed as part of these changes, so the PR attached to this issue doesn't remove any tooltips.

[jggautier]

To share the Style Guide, @TaniaSchlatter and I thought it would be best to include a link to the Google Doc in the Admin Guide's Metadata Customization page, maybe in a "Style Guide" section after the "Introduction" section. After the guide's been tested more (i.e. we get more feedback as it's reviewed and used more often to apply the guidelines to the application's other metadata field names, tooltips and watermarks), we could consider moving the text into the actual guides.

So the last to do for this issue is for me to prepare the style guide to be able to share more widely and add it the Metadata Customization page:

• [ ] Copy the Google Doc into a Google Doc that can live in IQSS's "Dataverse" Google Drive folder
• [ ] Move the notes and questions into a Google Doc that lists the unresolved issues discussed during reviews of the changes to the Citation metadatablock.
• [x] Create an "epic" GitHub issue listing each of the unresolved issues and referencing any existing GitHub issues and discussion in other channels (e.g. the Dataverse Community Group (Google Group))
• [x] In the PR with the changes to the metadata fields, edit the Metadata Customization page of the Admin Guides to include a Style Guide section with a link to the Style Guide

[jggautier]

We've decided to add the guidelines to the Style Guide, in a new page called "Text" for style guidelines related to text. The page, created in the PR associated with this issue, is called "Text" and will include a link to the Google Doc where we're keeping the metadata text guidelines for now (since we expect frequent changes to it).

In the "Tips from the Dataverse Community" section of the Metadata Customization page, I mention and link to the Style Guide and its "Text" page.

I hope by the end of this week to have the Google Doc organized enough so that the link to it can be included in the Text page and that should be the last to-do for this issue.

[jggautier]

The Style Guide "Text" page is updated. Moving the PR to the review column.

[mreekie]

Sprint:

• 8127 goes into the next sprint (Needs a new PR)

• See: https://github.com/IQSS/dataverse/pull/8592#issuecomment-1124209003

[pdurbin]

PR #8592 was just merged so as discussed I just put this issue in "Next Sprint". Also as discussed, we need a new PR.

[jggautier]

I just submitted the changes in a new PR.

[mreekie]

Prio:

• This should be straightforward to move through.
• High priority to get through.