Add documentation standards and structure for field mapping tools

Author: MrHinsh

.github/instructions/docs.content.docs.instructions.md

@@ -0,0 +1,59 @@
+---
+applyTo: "docs/content/docs/**"
+---
+
+# Documentation Standards
+
+All documentation content **must stay in sync with the codebase**.  
+Every page must accurately reflect the associated **data files** and **schemas**.
+
+---
+
+## Front Matter
+
+Each documentation file **may include** the following properties:
+
+- **dataFile**: Path to the generated documentation data file (stored in `docs/data/classes`)  
+  Example: `reference.tools.fieldmappingtool.yaml`
+
+- **schemaFile**: Path to the JSON schema file (stored in `docs/static/schema`)  
+  Example: `schema.tools.fieldmappingtool.json`
+
+> ⚠️ Documentation pages **must not** contain options, properties, or samples that do not exist in the corresponding `dataFile`.
+
+---
+
+## Documentation Structure
+
+Documentation files should generally include these sections (in order):
+
+1. **Overview**  
+   - Subsections: *How It Works*, *Use Cases*  
+
+2. **Configuration Structure**  
+   - Subsections: *Options*, *Sample*, *Defaults*, *Basic Examples*, *Complex Examples*  
+
+3. **Common Scenarios**  
+   - A list of common scenarios with supporting samples  
+
+4. **Good Practices**  
+   - Focus on maintainability, readability, and clarity  
+
+5. **Troubleshooting**  
+   - Common issues and their resolutions  
+
+6. **Schema**  
+   - Use the `{{< class-schema >}}` shortcode to render the schema from `schemaFile`  
+
+---
+
+## Rules
+
+- **Options** → use `{{< class-options >}}` to render the options table from `dataFile`.  
+- **Sample** → use `{{< class-sample sample="sample" >}}` to render the main sample from `dataFile`.  
+- **Defaults** → use `{{< class-sample sample="defaults" >}}` to render defaults from `dataFile`.  
+- **Basic Examples / Complex Examples** →  
+  - Include generated samples based on the `dataFile`.  
+  - Cross-reference the class object and its usage context.  
+
+---

docs/content/docs/reference/field-maps/field-to-tag-field-map/index.md

@@ -67,14 +67,14 @@ This field map is commonly used for:
 }
 ```
 
-#### Prefixed Tag Creation
+#### Formatted Tag Creation
 
 ```json
 {
   "FieldMapType": "FieldToTagFieldMap",
   "ApplyTo": ["*"],
   "sourceField": "Microsoft.VSTS.Common.Priority",
-  "tagPrefix": "Priority-"
+  "formatExpression": "Priority-{0}"
 }
 ```
 
@@ -96,7 +96,7 @@ This field map is commonly used for:
   "FieldMapType": "FieldToTagFieldMap",
   "ApplyTo": ["Feature"],
   "sourceField": "Custom.BusinessValue",
-  "tagPrefix": "BizValue-"
+  "formatExpression": "BizValue-{0}"
 }
 ```
 
@@ -161,13 +161,13 @@ This field map is commonly used for:
     "FieldMapType": "FieldToTagFieldMap",
     "ApplyTo": ["*"],
     "sourceField": "Custom.Department",
-    "tagPrefix": "Dept-"
+    "formatExpression": "Dept-{0}"
   },
   {
     "FieldMapType": "FieldToTagFieldMap",
     "ApplyTo": ["*"],
     "sourceField": "Custom.Component",
-    "tagPrefix": "Component-"
+    "formatExpression": "Component-{0}"
   }
 ]
 ```
@@ -186,7 +186,7 @@ This field map is commonly used for:
     "FieldMapType": "FieldToTagFieldMap",
     "ApplyTo": ["Bug"],
     "sourceField": "Custom.BugType",
-    "tagPrefix": "Type-"
+    "formatExpression": "Type-{0}"
   }
 ]
 ```

docs/content/docs/reference/field-maps/tree-to-tag-field-map/index.md

@@ -57,43 +57,36 @@ This field map is essential for:
 
 ### Basic Examples
 
-#### Area Path to Tags
+#### Skip Root Levels and Apply Time Travel
 
 ```json
 {
   "FieldMapType": "TreeToTagFieldMap",
   "ApplyTo": ["*"],
-  "sourceField": "System.AreaPath",
-  "tagPrefix": "Area-",
-  "includeCompletePath": true,
-  "includeIndividualLevels": false
+  "toSkip": 2,
+  "timeTravel": 0
 }
 ```
 
-#### Iteration Path with Level Tags
+#### Skip First Level Only
 
 ```json
 {
   "FieldMapType": "TreeToTagFieldMap",
-  "ApplyTo": ["*"],
-  "sourceField": "System.IterationPath", 
-  "tagPrefix": "Sprint-",
-  "includeCompletePath": false,
-  "includeIndividualLevels": true
+  "ApplyTo": ["User Story", "Bug"],
+  "toSkip": 1,
+  "timeTravel": 0
 }
 ```
 
-#### Complete Path and Level Breakdown
+#### Use Historical Area Path Values
 
 ```json
 {
   "FieldMapType": "TreeToTagFieldMap",
-  "ApplyTo": ["User Story", "Bug"],
-  "sourceField": "System.AreaPath",
-  "tagPrefix": "Team-",
-  "includeCompletePath": true,
-  "includeIndividualLevels": true,
-  "levelSeparator": " > "
+  "ApplyTo": ["*"],
+  "toSkip": 0,
+  "timeTravel": 6
 }
 ```
 
@@ -141,10 +134,8 @@ When teams are restructuring but want to maintain historical context:
 {
   "FieldMapType": "TreeToTagFieldMap",
   "ApplyTo": ["*"],
-  "sourceField": "System.AreaPath",
-  "tagPrefix": "OriginalTeam-",
-  "includeCompletePath": true,
-  "includeIndividualLevels": false
+  "toSkip": 1,
+  "timeTravel": 0
 }
 ```
 
@@ -156,10 +147,8 @@ Maintaining sprint information for historical analysis:
 {
   "FieldMapType": "TreeToTagFieldMap", 
   "ApplyTo": ["*"],
-  "sourceField": "System.IterationPath",
-  "tagPrefix": "CompletedIn-",
-  "includeCompletePath": true,
-  "includeIndividualLevels": false
+  "toSkip": 0,
+  "timeTravel": 3
 }
 ```
 
@@ -172,60 +161,63 @@ Creating tags for different organizational levels:
   {
     "FieldMapType": "TreeToTagFieldMap",
     "ApplyTo": ["*"],
-    "sourceField": "System.AreaPath",
-    "tagPrefix": "Division-",
-    "includeCompletePath": false,
-    "includeIndividualLevels": true
+    "toSkip": 2,
+    "timeTravel": 0
   },
   {
     "FieldMapType": "TreeToTagFieldMap",
     "ApplyTo": ["*"], 
-    "sourceField": "System.IterationPath",
-    "tagPrefix": "Release-",
-    "includeCompletePath": true,
-    "includeIndividualLevels": false
+    "toSkip": 0,
+    "timeTravel": 6
   }
 ]
 ```
 
 ## Best Practices
 
 ### Tag Organization
+
 - Use consistent prefixes to group related path tags
 - Consider tag naming conventions that align with organizational standards
 - Plan for tag management and cleanup procedures
 
 ### Performance Considerations
+
 - Monitor tag proliferation in large organizations
 - Consider the impact on query performance
 - Balance between detail and manageability
 
 ### Migration Planning
+
 - Document the mapping strategy for stakeholders
 - Test with representative data before full migration
 - Coordinate with teams on new tagging conventions
 
 ## Integration with Other Field Maps
 
 ### Complementary Usage
+
 - **Field Clear Map**: Clear original path fields after tag creation
 - **Field Skip Map**: Preserve original paths while adding tags
 - **Field Value Map**: Transform path values before tag conversion
 
 ### Sequential Processing
+
 - Tree To Tag maps typically run after basic field mappings
 - Consider order when combining with other path-related mappings
 - Ensure tag creation doesn't conflict with other field operations
 
 ## Troubleshooting
 
 ### Common Issues
+
 - **Invalid Path Formats**: Ensure source paths follow Azure DevOps conventions
 - **Tag Length Limits**: Monitor generated tag lengths
 - **Duplicate Tags**: Handle cases where multiple paths generate same tags
 - **Special Characters**: Test with paths containing special characters
 
 ### Validation Tips
+
 - Test with various path structures
 - Verify tag generation with sample data
 - Check for tag naming conflicts