📝 docs(powershell): add script for updating documentation

- introduce Update-Docs.ps1 script to automate the update of documentation by processing Hugo Markdown files
- integrate with existing IncludesForAll.ps1 for consistent logging

📝 docs(content): enhance documentation with descriptions

- add descriptions to various documentation files to improve clarity and understanding
- standardize metadata across multiple documentation files for uniformity

Author: MrHinsh

.powershell/docs/Update-Docs.ps1

@@ -0,0 +1,32 @@
+# Helpers
+. ./.powershell/docs/_includes/IncludesForAll.ps1
+$levelSwitch.MinimumLevel = 'Information'
+
+$hugoMarkdownObjects = Get-RecentHugoMarkdownResources -Path ".\docs\content\docs\" 
+
+foreach ($hugoMarkdown in $hugoMarkdownObjects) {
+
+    if ( $hugoMarkdown.FrontMatter.dataFile) {
+        $classDataFile = (Join-Path "docs" $hugoMarkdown.FrontMatter.dataFile)
+        if (Test-Path -Path $classDataFile) {
+            $classData = Get-Content -Path $classDataFile -Raw | ConvertFrom-Yaml
+            Write-InformationLog $classData.description
+            if ($classData.description -ne "missing XML code comments") {
+                $newDescription = $classData.description
+            }            
+        }
+    }
+
+    If ($newDescription -eq $null) {
+        Write-ErrorLog "No description found for $($hugoMarkdown.FilePath)"
+        continue
+    }
+
+
+    Update-Field -FieldName 'description' -FieldValue $newDescription -frontMatter $hugoMarkdown.frontMatter -addAfter "title"
+    Save-HugoMarkdown -HugoMarkdown $hugoMarkdown -Path $hugoMarkdown.FilePath
+   
+
+    
+
+}

docs/content/docs/get-started/getting-started/index.md

@@ -1,5 +1,6 @@
 ---
 title: 'Tutorial: Get started with the Azure DevOps Migration Tools'
+description: Performs mathematical calculations on numeric fields using NCalc expressions during migration.
 short_title: Get Started
 weight: 1
 aliases:

docs/content/docs/get-started/version-control/index.md

@@ -1,8 +1,8 @@
 ---
 title: Getting Started with Git and TFVC Version Control
-short_title: Version Control
 description: |
   While we do not migrate source control for you, we do have tools to maintain the links between work items and source code.
+short_title: Version Control
 aliases:
 - /version-control/
 date: 2025-06-24T12:07:31Z

docs/content/docs/how-to/_index.md

@@ -1,8 +1,8 @@
 ---
 title: How-To Guides for Azure DevOps Migration Tools
-short_title: How-To Guides
 description: |
   This section provides step-by-step guides on how to use the Azure DevOps Migration Tools effectively, covering various aspects of migration and configuration.
+short_title: How-To Guides
 weight: 3
 date: 2025-06-24T12:07:31Z
 discussionId: 2826

docs/content/docs/how-to/creating-iteration-and-area-maps/index.md

@@ -1,12 +1,12 @@
 ---
-title: "How-To: Creating area and iteration maps"
-short_title: Creating area and iteration maps
+title: 'How-To: Creating area and iteration maps'
 description: |
   This guide explains how to create area and iteration maps for Azure DevOps Migration Tools, allowing you to adapt old locations to new ones during migration.
+short_title: Creating area and iteration maps
 discussionId: 1846
 date: 2025-06-24T12:07:31Z
----
 
+---
 As per the [documentation]({{< ref "docs/reference/tools/tfs-node-structure-tool" >}}), you need to add Iteration Maps and Area Maps that adapt the old locations to new ones that are valid in the Target.
 
 Before your migration starts, it will validate that all of the Areas and Iterations from the **Source** work items revisions exist on the **Target**. Any that do not exist will be flagged in the logs, and if you have `"StopMigrationOnMissingAreaIterationNodes": true,` set, the migration will stop just after it outputs a list of the missing nodes.

docs/content/docs/how-to/migrating-plans-and-suites/index.md

@@ -1,12 +1,12 @@
 ---
-title: "How-to: Migrating Plans and Suites"
-short_title: Migrating Plans and Suites
+title: 'How-to: Migrating Plans and Suites'
 description: |
   This guide explains how to migrate Test Plans and Suites in Azure DevOps, including handling Shared Steps and Shared Parameters, and rebuilding Test Plans and Suites.
+short_title: Migrating Plans and Suites
 discussionId: 2049
 date: 2025-06-24T12:07:31Z
----
 
+---
 Migrating Plans and Suites is quite convoluted since Shared Steps, which we need to map, can't have a custom field.
 
 1. Migrate Basic Work Items

docs/content/docs/how-to/user-mappings/index.md

@@ -1,12 +1,12 @@
 ---
-title: "How-To: User Mappings"
-short_title: User Mappings
+title: 'How-To: User Mappings'
 description: |
   This guide explains how to map users between source and target systems in Azure DevOps migrations, ensuring integrity across different systems.
+short_title: User Mappings
 discussionId: 2266
 date: 2025-06-24T12:07:31Z
----
 
+---
 There was a request to have the ability to map users to try and maintain integrity across different systems. We added a `TfsUserMappingEnricher` that allows you to map users from Source to Target... this is not free and takes some work. Running the `ExportUsersForMappingConfig` to get the list of users will produce:
 
 ```

docs/content/docs/reference/_index.md

@@ -1,15 +1,17 @@
 ---
 title: Reference for Azure DevOps Migration Tools
+description: Performs mathematical calculations on numeric fields using NCalc expressions during migration.
 short_title: Reference
 weight: 1000
 date: 2025-06-24T12:07:31Z
 discussionId: 2821
 aliases:
-  - /learn/azure-devops-migration-tools/reference/
-  - /learn/azure-devops-migration-tools/reference/index.md
-  - /learn/azure-devops-migration-tools/reference/_index.md
-  - /learn/azure-devops-migration-tools/reference/overview/
-  - /learn/azure-devops-migration-tools/reference/overview/index.md
-  - /learn/azure-devops-migration-tools/Reference/
+- /learn/azure-devops-migration-tools/reference/
+- /learn/azure-devops-migration-tools/reference/index.md
+- /learn/azure-devops-migration-tools/reference/_index.md
+- /learn/azure-devops-migration-tools/reference/overview/
+- /learn/azure-devops-migration-tools/reference/overview/index.md
+- /learn/azure-devops-migration-tools/Reference/
+
 ---
 

docs/content/docs/reference/endpoints/_index.md

@@ -1,12 +1,13 @@
 ---
 title: Endpoints
-short_title: Endpoints
 description: |
   This section provides an overview of the endpoints used in the Azure DevOps Migration Tools, including their configuration and usage.Endpoints are used to define the access to TFS/Azure DevOps servers. They are used to connect to the source and target servers for migration.
+short_title: Endpoints
 date: 2025-06-24T12:07:31Z
 discussionId: 2799
 aliases:
-  - /learn/azure-devops-migration-tools/Reference/Endpoints/
-  - /Reference/Processors/Endpoints/index.md
+- /learn/azure-devops-migration-tools/Reference/Endpoints/
+- /Reference/Processors/Endpoints/index.md
+
 ---
 Endpoints are defined in the `endpoints` section of the configuration file. Each endpoint must have a unique name and specify the type of server it connects to, such as Azure DevOps Services, Azure DevOps Server, or TFS.

docs/content/docs/reference/endpoints/azure-devops-endpoint/index.md

@@ -4,14 +4,14 @@ description: Azure DevOps REST API endpoint implementation for connecting to Azu
 dataFile: data/reference.endpoints.azuredevopsendpoint.yaml
 slug: azure-devops-endpoint
 aliases:
-  - /docs/Reference/Endpoints/AzureDevOpsEndpoint
-  - /Reference/Endpoints/AzureDevOpsEndpoint
-  - /learn/azure-devops-migration-tools/Reference/Endpoints/AzureDevOpsEndpoint
-  - /learn/azure-devops-migration-tools/Reference/Endpoints/AzureDevOpsEndpoint/index.md
+- /docs/Reference/Endpoints/AzureDevOpsEndpoint
+- /Reference/Endpoints/AzureDevOpsEndpoint
+- /learn/azure-devops-migration-tools/Reference/Endpoints/AzureDevOpsEndpoint
+- /learn/azure-devops-migration-tools/Reference/Endpoints/AzureDevOpsEndpoint/index.md
 date: 2025-06-24T12:07:31Z
 discussionId: 2702
----
 
+---
 The Azure DevOps Endpoint is a critical component of the Azure DevOps Migration Tools that facilitates seamless connectivity between your migration processes and Azure DevOps organizations. This endpoint leverages the Azure DevOps REST API to provide comprehensive access to projects, work items, and other Azure DevOps resources.
 
 ## Purpose and Use Cases