Taxonomy Tag Management How-to Documentation Added

source/educators/how-tos/content-tagging-how-tos/manage_taxonomy_tags.rst

@@ -0,0 +1,293 @@
+.. _manage-taxonomy-tags:
+
+####################
+Manage Taxonomy Tags
+####################
+
+.. tags:: educator, how-to
+
+This guide describes how to create, organize, and manage tags within a taxonomy using the Taxonomy Detail. A detail page for a taxonomy can be found by navigating to the Taxonomies tab in the Studio, then selecting a taxonomy, which will then show that taxonomy's detail page. 
+
+Taxonomy Tab:
+
+.. image:: /_images/educator_how_tos/taxonomy_tab.png
+   :alt: Screenshot of the tabs in Studio home, with an arrow pointing to the Taxonomies tab.
+
+Taxonomy Overview Page:
+
+.. image:: /_images/educator_how_tos/taxonomy_overview_page.png
+   :alt: Screenshot of the Taxonomies Overview page showing multiple taxonomies.
+
+Taxonomy Detail Page:
+
+.. image:: /_images/educator_how_tos/taxonomy_detail_page.png
+   :alt: Screenshot of the Taxonomies Overview page showing multiple taxonomies.
+
+Overview
+********
+
+Tags allow you to organize and label content across:
+
+* Courses
+* Course content
+* Content libraries
+
+From the Taxonomy Detail page, you can:
+
+* View tag hierarchy
+* See usage counts
+* Add root-level tags and sub-tags
+* Rename existing tags
+* Delete tags and sub-tags
+
+View Tag Usage Counts
+*********************
+
+Each tag can display a usage count indicating how many unique content objects are associated with it.
+
+How Usage Is Calculated
+=======================
+
+Counts include:
+
+* Courses
+* Course content
+* Content library items
+
+Both published and unpublished content items are included.
+
+Each object counts once per tag, even if:
+
+* Multiple child tags are applied
+* The same tag is applied multiple times
+
+
+Parent Tag Aggregation
+======================
+
+Parent tags include usage from all child tags.
+
+Example:
+
+* ``Object A`` is tagged with ``Chemistry``
+* ``Object B`` is tagged with ``Physics`` and ``Chemistry``
+
+Parent tag ``Natural Science`` shows a usage count of ``2`` because
+``Object A`` and ``Object B`` are each counted once.
+
+.. image:: /_images/educator_how_tos/taxonomy_tag_usage_count.png
+   :alt: Screenshot of usage count badges displayed in the taxonomy tag list.
+
+No Usage Display
+================
+
+If a tag has no associated content, no usage count is shown.
+
+Add a Root-Level Tag
+********************
+
+To create a new top-level tag:
+
+#. Navigate to the Taxonomies page from Studio Home
+#. Choose a Taxonomy to add to and select it
+#. Select the + (plus) icon at the top of the tag list
+
+   .. image:: /_images/educator_how_tos/taxonomy_add_root_tag_button.png
+      :alt: Screenshot of the plus icon used to create a root-level tag.
+
+#. Enter a tag name in the inline input field
+
+   .. image:: /_images/educator_how_tos/taxonomy_add_root_tag_input.png
+      :alt: Screenshot of the inline input field for adding a root-level tag.
+
+#. Click Save or press Enter
+
+After the tag is saved, the new tag appears at the top of the list and a
+success notification is displayed.
+
+Cancel Tag Creation
+==============================
+
+To cancel a tag creation, select Cancel or press Esc. The input
+row is removed, and the tag is not created.
+
+   .. image:: /_images/educator_how_tos/taxonomy_cancel_tag.png
+      :alt: Screenshot of the cancel button to cancel the process of adding a root-level tag.
+
+Validation Rules
+===============================
+
+You cannot save a tag if:
+
+* The input is empty
+* The input contains only whitespace
+* The name includes invalid characters:
+
+  * Leading or trailing whitespace
+  * TAB character
+  * > (space-greater-than-space)
+  * ; (semicolon) 
+
+* The name duplicates an existing tag, regardless of letter casing.
+
+  * Example: “Learning” and “learning” are considered duplicates
+
+Add a Sub-Tag
+*************
+
+To create a tag under an existing parent:
+
+#. Locate the parent tag
+#. Open the actions menu by selecting the three dots
+#. Select Add sub-tag
+
+   .. image:: /_images/educator_how_tos/taxonomy_add_sub_tag_menu.png
+      :alt: Screenshot of the Add sub-tag option in the tag actions menu.
+
+#. Enter the sub-tag name
+
+   .. image:: /_images/educator_how_tos/taxonomy_add_sub_tag_input.png
+      :alt: Screenshot of the inline input field for adding a sub-tag.
+
+#. Select Save, or press Enter
+
+After the sub-tag is saved, the sub-tag appears directly beneath the parent tag
+and is indented to reflect hierarchy.
+
+Cancel Tag Creation
+=======================
+
+To cancel tag creation, select Cancel or press Esc. The row is
+removed without saving.
+
+Sub-Tag Validation Rules
+========================
+
+Sub-tags follow the same rules as root tags:
+
+* No empty or whitespace-only names
+* No invalid characters
+* No duplicates under the same parent (case-insensitive)
+
+Rename a Tag
+************
+
+To rename a tag:
+
+#. Open the actions menu next to the tag by selecting the three dots
+#. Select Rename
+
+   .. image:: /_images/educator_how_tos/taxonomy_rename_tag_menu.png
+      :alt: Screenshot of the Rename option in the tag actions menu.
+
+#. Edit the tag name inline
+#. Select Save, or press Enter
+
+After the tag is renamed:
+
+* The updated name is displayed immediately.
+* A success notification appears.
+* All tag associations are updated across courses, libraries, and the search
+  index.
+
+Cancel Rename
+=============
+
+To cancel a rename, select Cancel or press Esc. The original name is
+restored, and no changes are saved.
+
+.. note::
+
+   The Save button is disabled until the tag name is changed. Usage counts
+   remain unchanged after rename.
+
+Delete a Tag
+************
+
+.. warning::
+
+   Deleting a parent tag also deletes its sub-tags. Any uses of the deleted tag
+   or its sub-tags are removed from associated content.
+
+Delete a Tag Without Sub-Tags
+=============================
+
+To delete a tag that does not have sub-tags:
+
+#. Open the actions menu for the tag
+#. Select Delete
+
+   .. image:: /_images/educator_how_tos/taxonomy_delete_tag_menu.png
+      :alt: Screenshot of the Rename option in the tag actions menu.
+
+#. In the confirmation dialog, type ``DELETE``
+#. Confirm deletion
+
+Delete a Tag With Sub-Tags
+==========================
+
+To delete a tag that has sub-tags:
+
+#. Open the actions menu for the tag
+#. Select Delete
+#. Review the warning that sub-tags will also be deleted
+#. Type ``DELETE ALL # TAGS``, where ``#`` is the number of tags being deleted
+#. Confirm deletion
+
+After deletion:
+
+* The tag is removed
+* All sub-tags, if any, are removed
+* All tag associations are removed from content
+* A confirmation notification is displayed
+
+Keyboard Accessibility
+**********************
+
+All workflows support keyboard interaction. Users can:
+
+* Navigate menus using keyboard controls
+* Trigger actions such as Rename, Delete, and Add sub-tag
+* Save using Enter
+* Cancel using Esc
+
+Permissions
+***********
+
+Only users with admin permissions can:
+
+* Add root-level tags
+* Add sub-tags
+* Rename tags
+* Delete tags
+
+Users without admin permissions do not see the controls for these actions.
+
+.. seealso::
+
+ :ref:`build-taxonomy-using-template` (how-to)
+
+ :ref:`create-flat-taxonomy` (how-to)
+
+ :ref:`import-export-taxonomy` (how-to)
+
+ :ref:`Update/Re-import a taxonomy` (how-to)
+
+ :ref:`tag-ids-for-taxonomy-import` (concept)
+
+ :ref:`Manage Permissions on a Taxonomy` (how-to)
+
+ :ref:`add-tags-to-a-course` (how-to)
+
+ :ref:`Add and delete tags on course content` (how-to)
+
+ :ref:`Export tag data from a course` (how-to)
+
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Working Group Reviewer        | Release        | Test situation                 |
++--------------+-------------------------------+----------------+--------------------------------+
+| 2026-05-05   | Unicon                        | Verawood       | Pass                           |
++--------------+-------------------------------+----------------+--------------------------------+

source/educators/navigation/advanced_features.rst

@@ -112,6 +112,7 @@ Course Tags and Taxonomies
    ../how-tos/content-tagging-how-tos/import_export_a_taxonomy.rst
    ../how-tos/content-tagging-how-tos/Create_flat_taxonomy_by_uploading_CSV.rst
    ../how-tos/content-tagging-how-tos/update_reimport_taxonomy.rst
+   ../how-tos/content-tagging-how-tos/manage_taxonomy_tags.rst
    ../concepts/advanced_features/why_taxonomy_tag_id.rst
    ../how-tos/content-tagging-how-tos/manage_permissions_taxonomy.rst
    ../how-tos/content-tagging-how-tos/add_delete_course_tags.rst
@@ -207,4 +208,4 @@ Use Custom Courses (CCX)
    :glob:
 
 
-   ../how-tos/enable_ccx.rst
+   ../how-tos/enable_ccx.rst