Custom GitHub Copilot Documentation Agent¶
Overview¶
The ODA Canvas project includes a custom GitHub Copilot agent (@docs) specialized in creating and improving markdown documentation and PlantUML diagrams. This agent helps maintain consistency across all project documentation while following established patterns and standards.
Purpose¶
The documentation agent addresses key documentation challenges:
Consistency: Ensures all documentation follows the same writing style and structure
Completeness: Helps identify and fill documentation gaps
Quality: Maintains high-quality technical writing across all markdown files
Efficiency: Accelerates documentation creation with intelligent templates
Maintenance: Validates cross-references and keeps documentation synchronized
Agent Capabilities¶
1. README Generation and Enhancement¶
The agent can create or enhance README files for:
Helm Charts (
charts/*/README.md)Adds contextual sections to complement helm-docs auto-generated content
Links to related operators and use cases
Provides usage examples and troubleshooting guidance
Operators (
source/operators/*/README.md)Creates comprehensive operator documentation
Generates PlantUML sequence diagrams
Includes development and testing instructions
Test Components (
feature-definition-and-test-kit/testData/*/README.md)Documents TMF API implementations
Describes component architecture and microservices
Provides installation and configuration details
2. Use-Case Documentation¶
Creates implementation-agnostic use case documentation following TM Forum ODA standards:
Structured scenarios with PlantUML sequence diagrams
Clear assumptions and prerequisites
Links to BDD feature tests
Alignment with ODA Component Specification
3. PlantUML Diagram Generation¶
Generates sequence diagrams with:
Consistent actor naming (Canvas, Component, Operator, Kubernetes API)
Auto-constructed proxy URLs for rendering
Source
.pumlfiles in appropriatepumlFiles/directoriesStandard formatting and styling
4. Cross-Reference Validation¶
Validates and maintains documentation links:
Bidirectional links between use cases and BDD features
Operator-to-use-case references
Relative path accuracy
PlantUML diagram URL validation
5. Terminology Consistency¶
Enforces consistent terminology:
“ODA Canvas” (not just “Canvas”)
“ODA Component” (always capitalized)
“Software Operators” (capitalized)
Proper use of backticks for technical elements
British spelling (“Behaviour-Driven Development”)
How to Use the Agent¶
Activation Methods¶
1. Keyword Invocation (@docs)¶
Explicitly invoke the agent when editing any markdown file:
@docs Create a README for the api-gateway-operator chart
@docs Generate a use case for component dependency management
@docs Create a sequence diagram showing authentication flow
@docs Enhance this README with troubleshooting section
@docs Validate cross-references in this use case
2. Auto-Suggestions¶
The agent automatically provides suggestions when you:
Open any README file
Create a new markdown file
Edit use case documentation
Work with PlantUML diagrams
Common Use Cases¶
Creating a New Chart README¶
@docs Create a comprehensive README for charts/new-operator-chart that complements helm-docs
The agent will:
Analyze the chart structure
Apply the chart README template
Add Overview and Architecture sections
Link to related operators and use cases
Include usage examples
Preserve helm-docs auto-generated content
Generating a Use Case¶
@docs Create a use case for UC017 component auto-scaling
The agent will:
Apply the use case template
Follow naming conventions
Create placeholder sections for scenarios
Generate PlantUML diagram references
Link to related BDD features
Creating a Sequence Diagram¶
@docs Generate a PlantUML sequence diagram showing component installation flow
The agent will:
Create a
.pumlfile in the appropriatepumlFiles/directoryUse standard Canvas actors
Generate the proxy URL for rendering
Add the source code link
Enhancing Existing Documentation¶
@docs Add a troubleshooting section to this README based on common issues
@docs Validate and fix all cross-references in this document
@docs Ensure this use case follows the writing style guide
Agent Configuration¶
Configuration File¶
The agent is configured in .github/copilot-agent-docs.yml with:
Activation keywords:
@docsAuto-trigger patterns:
**/*README.md,**/*.mdFile scope:
**/*.md,**/*.puml(limited to documentation files)Knowledge base: References to key documentation and style guides
Templates directory:
docs/templates/
Knowledge Base¶
The agent has access to:
Project Overview: .github/copilot-instructions.md
Writing Style Guide: docs/writing-style.md
Use Case Conventions: usecase-library/use-case-naming-conventions.md
Exemplar Documentation: README files, design documents, use cases
Templates¶
Five templates guide documentation creation:
Chart README Template - docs/templates/chart-readme-template.md
Operator README Template - docs/templates/operator-readme-template.md
Use Case Template - docs/templates/use-case-template.md
Test Component README Template - docs/templates/test-component-readme-template.md
PlantUML Sequence Template - docs/templates/plantuml-sequence-template.puml
See docs/templates/README.md for template usage details.
Agent Behavior and Rules¶
What the Agent Will Do¶
✅ Create and edit markdown files (.md)
✅ Generate PlantUML diagrams (.puml)
✅ Validate cross-references between documentation
✅ Suggest improvements based on style guide
✅ Apply templates consistently
✅ Auto-construct PlantUML proxy URLs
✅ Preserve helm-docs content between markers
✅ Enforce terminology standards
What the Agent Will NOT Do¶
❌ Edit source code files (.py, .java, .js, .ts, etc.)
❌ Modify helm-docs generated content between markers
❌ Change version badges without approval
❌ Create standalone “Canvas” (always “ODA Canvas”)
❌ Use American spelling for “Behavior” (British: “Behaviour”)
❌ Break existing PlantUML URLs
Helm-docs Preservation¶
For Helm chart READMEs, the agent:
Preserves all content between
<!--- BEGIN PARAMS --->and<!--- END PARAMS --->Adds contextual sections (Overview, Architecture, Usage, Troubleshooting)
Maintains version badges and footer attribution
Complements rather than replaces helm-docs
Example structure:
# Chart Name
## Overview
[Agent-generated contextual content]
## Architecture
[Agent-generated content with links]
<!--- BEGIN PARAMS --->
[helm-docs auto-generated - PRESERVED]
<!--- END PARAMS --->
## Usage Examples
[Agent-generated examples]
## Troubleshooting
[Agent-generated troubleshooting]
PlantUML Workflow¶
Diagram Generation¶
When creating a PlantUML diagram, the agent:
Creates source file in appropriate
pumlFiles/directory:Use cases:
usecase-library/pumlFiles/Design docs:
docs/pumlFiles/Operators:
source/operators/pumlFiles/
Uses kebab-case naming:
uc002-install-component.pumlGenerates local SVG reference:

Adds source link:
[plantUML code](pumlFiles/diagram-name.puml)
Standard Actors¶
PlantUML diagrams use consistent actors:
Canvas - ODA Canvas environment
Component - ODA Component being managed
Operator - Software Operator (Component, API, Identity, etc.)
Kubernetes API - K8s control plane
Developer - Human actor
API Gateway - Istio/Kong/Apisix gateway
Identity Management - Keycloak or similar
Writing Style Guidelines¶
The agent follows comprehensive writing style guidelines documented in docs/writing-style.md:
Voice and Tone¶
Active voice for technical descriptions
Imperative mood for instructions
“We” for organizational voice, “you” for reader instructions
Technical Terminology¶
Capitalize: “ODA Canvas”, “ODA Component”, “Software Operators”
Hyphenate: “cloud-native”, “machine-readable”, “sub-resources”
Backticks for: Kubernetes resources, commands, file paths, versions
Structure Patterns¶
Title case for H1 document titles
Sentence case for H2/H3 subsections
Question format for design documents
Code and Links¶
Always use language tags for code blocks
Inline links with relative paths for internal references
Introductory phrases: “see [link]”, “For more information…”
See the full Writing Style Guide for detailed conventions.
Cross-Reference Validation¶
The agent validates and maintains documentation links:
Bidirectional Links¶
Use Cases ↔ BDD Features:
Use case must reference BDD features
BDD features must reference use case
Tags match:
@UC002in feature file ↔UC002-*.md
Operators → Use Cases:
Operator READMEs reference use case diagrams
Use case diagrams show operators involved
Link Validation¶
Relative paths verified (
./for same dir,../for parent)Target files must exist
PlantUML URLs format checked
Branch references appropriate (main vs. feature branch)
Success Criteria¶
Documentation created or enhanced by the agent should meet:
Completeness¶
✅ All required sections present per template
✅ Cross-references valid and bidirectional
✅ PlantUML diagrams render correctly
Consistency¶
✅ Terminology matches glossary
✅ Heading hierarchy follows patterns
✅ Code formatting consistent
Quality¶
✅ Writing style matches docs/writing-style.md
✅ Examples are practical and tested
✅ Links are relative and valid
Troubleshooting¶
Agent Not Responding¶
Issue: Agent doesn’t respond to @docs keyword
Solutions:
Ensure you’re editing a markdown (
.md) or PlantUML (.puml) fileCheck GitHub Copilot is enabled for your workspace
Verify you have the latest Copilot extension
Agent Suggestions Not Helpful¶
Issue: Agent provides generic suggestions instead of Canvas-specific content
Solutions:
Provide more context in your prompt: “@docs Create a README for the component-operator chart in the ODA Canvas”
Reference specific templates: “@docs Use the operator README template”
Include use case or operator names for better context
PlantUML Diagrams Not Rendering¶
Issue: PlantUML proxy URL shows error
Solutions:
Verify the
.pumlfile exists in the correctpumlFiles/directoryCheck the GitHub branch reference in the URL (main vs. feature branch)
Ensure PlantUML syntax is valid (test at plantuml.com)
helm-docs Content Modified¶
Issue: Agent accidentally edited helm-docs generated content
Solutions:
Verify markers are present:
<!--- BEGIN PARAMS --->and<!--- END PARAMS --->Regenerate helm-docs content:
helm-docs -c charts/{chart-name}Report issue if agent bypassed markers
Best Practices¶
For Contributors¶
Always use
@docsfor new documentation - Ensures consistency from the startReview agent suggestions - Agent is helpful but verify accuracy
Follow templates - Templates ensure nothing is missed
Validate links - Check that cross-references work
Test PlantUML diagrams - Verify diagrams render before committing
For Reviewers¶
Check template adherence - Ensure all required sections present
Verify terminology - “ODA Canvas”, “ODA Component” capitalized
Validate cross-references - Links should be bidirectional where appropriate
Test examples - Code examples should be accurate and tested
Review PlantUML diagrams - Diagrams should render and be accurate
Future Enhancements¶
Potential improvements to the documentation agent:
Planned Features¶
Automated link checking - CI/CD integration to validate all links
Diagram validation - Pre-commit hooks to check PlantUML syntax
Template versioning - Track template evolution over time
Documentation metrics - Measure completeness and consistency
Multi-language support - Templates for API specifications
Feedback and Contributions¶
To improve the documentation agent:
Report issues - Create GitHub issue with
documentationlabelSuggest improvements - Propose template enhancements
Share patterns - Contribute exemplar documentation
Update style guide - Submit PRs to docs/writing-style.md
References¶
This documentation agent is designed to maintain high-quality, consistent documentation across the ODA Canvas project. For questions or suggestions, see CONTRIBUTING.md.