IQSS · kcondon · Mar 23, 2022 · Feb 28, 2022 · Feb 28, 2022 · Feb 28, 2022
diff --git a/doc/release-notes/8127-citation-field-improvements.md b/doc/release-notes/8127-citation-field-improvements.md
@@ -0,0 +1,16 @@
+### Improvements to fields that appear in the Citation metadata block
+
+Grammar, style and consistency improvements have been made to the titles, tooltip description text, and watermarks of metadata fields that appear in the Citation metadata block.
+
+This includes fields that dataset depositors can edit in the Citation Metadata accordion (i.e. fields controlled by the citation.tsv and citation.properties files) and fields whose values are system-generated, such as the Dataset Persistent ID, Previous Dataset Persistent ID, and Publication Date fields (controlled by the bundles.properties file).
+
+The changes should provide clearer information to curators, depositors, and people looking for data about what the fields are for.
+
+A new page in the Style Guides called "Text" has also been added. The new page includes a section called "Metadata Text Guidelines" with a link to a Google Doc where the guidelines are being maintained for now since we expect them to be revised frequently.
+
+### Additional Upgrade Steps
+
+Update the Citation metadata block:
+
+- `wget https://github.com/IQSS/dataverse/releases/download/v#.##/citation.tsv`
+- `curl http://localhost:8080/api/admin/datasetfield/load -X POST --data-binary @citation.tsv -H "Content-type: text/tab-separated-values"`
diff --git a/doc/sphinx-guides/source/admin/metadatacustomization.rst b/doc/sphinx-guides/source/admin/metadatacustomization.rst
@@ -574,6 +574,8 @@ The scripts required can be hosted locally or retrieved dynamically from https:/
 Tips from the Dataverse Community
 ---------------------------------
 
+When creating new metadatablocks, please review the :doc:`/style/text` section of the Style Guide, which includes guidance about naming metadata fields and writing text for metadata tooltips.
+
 If there are tips that you feel are omitted from this document, please open an issue at https://github.com/IQSS/dataverse/issues and consider making a pull request to make improvements. You can find this document at https://github.com/IQSS/dataverse/blob/develop/doc/sphinx-guides/source/admin/metadatacustomization.rst
 
 Alternatively, you are welcome to request "edit" access to this "Tips for Dataverse Software metadata blocks from the community" Google doc: https://docs.google.com/document/d/1XpblRw0v0SvV-Bq6njlN96WyHJ7tqG0WWejqBdl7hE0/edit?usp=sharing

diff --git a/doc/sphinx-guides/source/style/index.rst b/doc/sphinx-guides/source/style/index.rst
@@ -14,3 +14,4 @@ This style guide is meant to help developers implement clear and appropriate UI
 
    foundations
    patterns
+   text
diff --git a/doc/sphinx-guides/source/style/text.rst b/doc/sphinx-guides/source/style/text.rst
@@ -0,0 +1,14 @@
+Text
+++++
+
+Here we describe the guidelines that help us provide helpful, clear and consistent textual information to users.
+
+.. contents:: |toctitle|
+  :local:
+
+Metadata Text Guidelines
+========================
+
+`Bootstrap <http://getbootstrap.com/css/#grid>`__ provides a responsive, fluid, 12-column grid system that we use to organize our page layouts.
+
+These guidelines are maintained in `a Google Doc <https://docs.google.com/document/d/1tY5t3gjrIgAGoRxVMWQSCh46fnbSmnFDLQ7aLkNLhJ8>`__ as we expect to make frequent changes to them. We welcome comments in the Google Doc.
diff --git a/scripts/api/data/metadatablocks/citation.tsv b/scripts/api/data/metadatablocks/citation.tsv
diff --git a/src/main/java/propertyFiles/Bundle.properties b/src/main/java/propertyFiles/Bundle.properties
@@ -878,9 +878,8 @@ advanced.search.files.variableName=Variable Name
 advanced.search.files.variableName.tip=The name of the variable's column in the data frame.
 advanced.search.files.variableLabel=Variable Label
 advanced.search.files.variableLabel.tip=A short description of the variable.
-advanced.search.datasets.persistentId.tip=The persistent identifier for the dataset.
-advanced.search.datasets.persistentId=Dataset Persistent ID
-advanced.search.datasets.persistentId.tip=The unique persistent identifier for a dataset, which can be a Handle or DOI in Dataverse.
+advanced.search.datasets.persistentId=Persistent Identifier
+advanced.search.datasets.persistentId.tip=The dataset's unique persistent identifier,either a DOI or Handle
 advanced.search.files.fileTags=File Tags
 advanced.search.files.fileTags.tip=Terms such "Documentation", "Data", or "Code" that have been applied to files.
 
@@ -1514,15 +1513,15 @@ dataset.message.termsFailure=The dataset terms could not be updated.
 dataset.message.label.fileAccess=File Access
 dataset.message.publicInstall=Files are stored on a publicly accessible storage server.
 dataset.metadata.publicationDate=Publication Date
-dataset.metadata.publicationDate.tip=The publication date of a dataset.
+dataset.metadata.publicationDate.tip=The date when the Dataset is published in this repository
 dataset.metadata.citationDate=Citation Date
 dataset.metadata.citationDate.tip=The citation date of a dataset, determined by the longest embargo on any file in version 1.0.
 dataset.metadata.publicationYear=Publication Year
 dataset.metadata.publicationYear.tip=The publication year of a dataset.
-dataset.metadata.persistentId=Dataset Persistent ID
-dataset.metadata.persistentId.tip=The unique persistent identifier for a dataset, which can be a Handle or DOI in Dataverse.
-dataset.metadata.alternativePersistentId=Previous Dataset Persistent ID
-dataset.metadata.alternativePersistentId.tip=A previously used persistent identifier for a dataset, which can be a Handle or DOI in Dataverse.
+dataset.metadata.persistentId=Persistent Identifier
+dataset.metadata.persistentId.tip=The dataset's unique persistent identifier, either a DOI or Handle
+dataset.metadata.alternativePersistentId=Previous Persistent Identifier
+dataset.metadata.alternativePersistentId.tip=A previously used persistent identifier for the Dataset, either a DOI or Handle
 file.metadata.preview=Preview
 file.metadata.filetags=File Tags
 file.metadata.persistentId=File Persistent ID