🤖Agent Instructions as an Operational Layer for the Product Wiki

October 01, 2025

🏗️ Background

In feature-area-aligned-product-documentation-wiki(Feature Area Aligned Product Documentation Wiki), a structured documentation model was established for the License Management product. That system introduced:

• Feature Areas as the primary organizing unit
• A consistent set of documentation artifacts per Feature Area
• Tight integration with Azure DevOps work items
• A canonical data model as the source of truth for entities and relationships

While that work defined how documentation is structured, it did not fully address how documentation is authored, maintained, and evolved in practice, particularly when editing content directly in VS Code and collaborating with automation and AI-assisted tooling.

This project focuses on closing that gap.

🎯 Objective

The goal of this project was to introduce a formal instruction layer that enables consistent, low-friction authoring of Feature Area documentation while preserving the structural guarantees of the underlying wiki system.

Specifically, the instruction text is intended to:

• Enable effective editing of Azure DevOps wiki content in VS Code
• Enforce documentation structure, formatting, and style conventions
• Reduce cognitive overhead during documentation updates
• Prevent accidental breakage of automated or embedded artifacts
• Provide clear guidance for AI-assisted content generation
• Support long-term maintainability of the documentation system

📚 Scope

The instruction text applies to Feature Area documentation within the License Management product wiki and governs:

• Main Feature Area pages
• Technical Reference documentation
• Support documentation
• Testing documentation

It explicitly does not replace the Feature Area information architecture; instead, it operationalizes it.

🛠️ Solution Overview

📄 Instruction Text as an Operational Artifact

The instruction text functions as a documentation operating manual embedded alongside the wiki content. Rather than relying on tribal knowledge or individual memory, it encodes documentation standards directly into the authoring workflow.

Key characteristics of the solution:

• Lives close to the documentation it governs
• Written for contributors and tooling, not end users
• Explicitly prescriptive rather than advisory
• Designed to be referenced continuously during editing

🚀 Key Capabilities Enabled

1️⃣ Consistent Authoring in VS Code

The instructions allow Feature Area documentation to be edited effectively outside the Azure DevOps web UI by:

• Defining required document types and sections
• Standardizing file naming conventions
• Locking down heading levels and anchor patterns
• Providing repeatable templates for common sections

This ensures that local editing, previewing, and committing changes does not degrade wiki consistency.

2️⃣ Style and Structure Enforcement

The instruction text enforces consistent documentation patterns across Feature Areas, including:

• Fixed four-part documentation model
• Standardized release item formatting
• Defined placement of use cases, requirements, and release entries
• Clear guidance on personas vs archetypes

This eliminates stylistic drift over time and across contributors.

3️⃣ Reduced Cognitive Load During Updates

By encoding decisions such as:

• Where release notes belong
• How detailed setup and verification steps should be
• How headings should be structured for predictable anchors

…the instructions remove the need to re-decide formatting and structure on every update. Contributors can focus on content accuracy and intent rather than mechanics.

4️⃣ Reliable Mermaid Diagram Usage

Mermaid diagrams are supported but deliberately constrained.

The instructions:

• Enforce Azure DevOps–compatible syntax
• Prohibit styling, themes, and visual customization
• Favor concise, conceptual diagrams over detailed flows
• Define node naming and layout preferences

This ensures diagrams render reliably and remain maintainable, especially when authored or updated via VS Code or AI tooling.

5️⃣ Protection of Automated and Embedded Artifacts

The instruction text explicitly identifies elements that must not be modified, including:

• Azure DevOps embedded query IDs
• Automated front matter and file structure
• .order navigation files
• Query-table syntax

This protects the integrity of automation that keeps documentation live and connected to work item tracking.

6️⃣ Improved AI-Assisted Authoring Outcomes

By making rules explicit, the instruction text improves the reliability of AI-assisted documentation generation.

The instructions constrain AI behavior around:

• Section placement
• Heading levels
• Diagram syntax
• Entity naming
• Archetype linking vs duplication

This allows AI tools to be used as accelerators without introducing structural or formatting errors that require manual cleanup.

🔗 Relationship to the Original Feature Area Wiki Design

The original Feature Area wiki design defined what exists and where it lives.

This project defines how that system is operated day to day.

Together, they form a complete documentation system:

• Information architecture provides consistency and navigability
• Instruction text provides execution discipline and durability

The instruction layer ensures that the original design remains viable as the number of features, contributors, and tooling integrations increases.

🌟 Outcomes

As implemented, this instruction-driven approach has resulted in:

• Faster and more consistent documentation updates
• Reduced formatting errors and rework
• Improved durability of diagrams and embedded queries
• Lower onboarding friction for new contributors
• Better alignment between product, engineering, QA, and support documentation

Most importantly, it ensures that documentation quality is a property of the system, not individual effort.

📝 Summary

This project formalizes the operational rules required to sustain a scalable, Feature Area–based product wiki. By introducing explicit instruction text alongside the documentation itself, it enables efficient VS Code–based editing, reliable automation, and consistent collaboration with AI tooling—while preserving the structural guarantees established by the original wiki design.

Categories: projects

Tags: product-management, systems, technology