ODA Canvas Documentation¶
This directory contains documentation resources, templates, and guides for contributors and developers working on the ODA Canvas project.
Contents¶
Documentation Guides¶
Writing Style Guide - Comprehensive guide to writing style conventions for all markdown documentation
Custom Copilot Agent - Guide to using the
@docsAI agent for documentation creation and enhancement
Templates¶
The templates/ directory contains standardized templates for creating consistent documentation:
Chart README Template - For Helm charts in
charts/directoryOperator README Template - For operators in
source/operators/directoryUse Case Template - For use cases in
usecase-library/directoryTest Component README Template - For test components in
feature-definition-and-test-kit/testData/PlantUML Sequence Template - For sequence diagrams
See templates/README.md for detailed usage instructions.
Developer Documentation¶
The developer/ directory contains technical guides for developers:
How-to guides for common development tasks
Architecture decision records
Development workflows and best practices
PlantUML Diagrams¶
The pumlFiles/ directory stores PlantUML source files for design documentation diagrams. For use case diagrams, see usecase-library/pumlFiles/.
Quick Start¶
For Contributors¶
Writing New Documentation¶
Invoke the documentation agent with
@docskeyword:@docs Create a README for the new-operator
Or use templates manually:
Browse templates/ directory
Copy relevant template
Fill in placeholders
Follow Writing Style Guide
Validate documentation:
Check all cross-references work
Verify terminology follows standards
Test code examples
Ensure PlantUML diagrams render
Improving Existing Documentation¶
Open the markdown file - Agent auto-suggests improvements
Or invoke explicitly:
@docs Add troubleshooting section to this README @docs Validate cross-references in this document
For Reviewers¶
When reviewing documentation PRs, verify:
✅ Template structure followed (if applicable)
✅ Writing style matches writing-style.md
✅ Terminology consistent (“ODA Canvas”, “ODA Component” capitalized)
✅ Cross-references valid and bidirectional
✅ Code examples tested and accurate
✅ PlantUML diagrams render correctly
✅ helm-docs content not manually edited (for charts)
Documentation Structure¶
Project-Wide Documentation Layers¶
The ODA Canvas documentation follows a hierarchical structure:
Level 1: Strategic Documentation
├── Canvas-design.md
├── SecurityPrinciples.md
├── Authentication-design.md
├── Event-based-integration-design.md
└── Observability-design.md
Level 2: Use Cases (Implementation-Agnostic)
└── usecase-library/UC*.md
Level 3: BDD Features (Executable Specifications)
└── feature-definition-and-test-kit/features/UC*.feature
Level 4: Implementation Documentation
├── source/operators/*/README.md
├── charts/*/README.md
└── feature-definition-and-test-kit/testData/*/README.md
Level 5: Operational Documentation
├── installation/README.md
└── docs/developer/*.md
Cross-Reference Patterns¶
Documentation should maintain bidirectional links:
Use Cases ↔ BDD Features - Use case references features; features reference use case
Operators → Use Cases - Operator READMEs reference use case diagrams
Charts → Operators - Chart READMEs link to operator implementations
Design Docs → Use Cases - Design epics reference implementing use cases
Writing Style¶
See the complete Writing Style Guide for detailed conventions.
PlantUML Diagrams¶
Creating Diagrams¶
Use the @docs agent to generate diagrams:
@docs Create a sequence diagram showing component installation flow
Or manually:
Customize actors and sequence
Save in appropriate
pumlFiles/directory:Use cases:
usecase-library/pumlFiles/Design docs:
docs/pumlFiles/Operators:
source/operators/pumlFiles/
Embedding Diagrams¶
Use local SVG files for better performance:

[plantUML code](pumlFiles/diagram-name.puml)
To convert PlantUML files to SVG:
node scripts/plantuml-to-svg.js path/to/diagram.puml
See plantuml-to-svg-guide.md for details.
Standard Actors¶
Use consistent actor names:
Canvas
Component
Operator
Kubernetes API
Developer
API Gateway
Identity Management
Custom Copilot Agent¶
The @docs agent assists with documentation creation and maintenance:
Capabilities¶
✅ Generate README files from templates
✅ Create use case documentation
✅ Generate PlantUML sequence diagrams
✅ Validate cross-references
✅ Enforce terminology standards
✅ Suggest improvements based on style guide
✅ Complement helm-docs for charts
Limitations¶
❌ Cannot edit source code files
❌ Cannot modify helm-docs generated content
❌ Limited to markdown and PlantUML files
See Custom Copilot Agent Guide for detailed usage.
Contributing to Documentation¶
Documentation Improvements¶
To improve documentation:
Identify the issue - Missing section, unclear explanation, broken links
Check templates - Does a template exist? Should it be updated?
Use the
@docsagent - Let it help with consistencyFollow style guide - Maintain writing conventions
Validate changes - Test links and examples
Submit PR - With clear description of improvements
Template Evolution¶
To propose template changes:
Create an issue - Describe proposed improvement
Provide rationale - Why is this change needed?
Show examples - Reference existing good documentation
Update template - Make changes in
docs/templates/Update style guide - If patterns change, update writing-style.md
Style Guide Updates¶
To update the writing style guide:
Analyze patterns - Review multiple markdown files
Identify inconsistencies - What needs standardization?
Propose convention - Suggest best practice
Provide examples - Show good vs. avoid patterns
Submit PR - Update writing-style.md
Documentation Quality¶
Quality Checklist¶
Before finalizing documentation, verify:
[ ] All required sections present (per template if applicable)
[ ] Headings follow capitalization rules
[ ] Technical terms properly capitalized and formatted
[ ] Code blocks have language tags
[ ] Links use relative paths for internal references
[ ] PlantUML diagrams render correctly
[ ] Cross-references are bidirectional where appropriate
[ ] Lists use consistent formatting
[ ] Tables are properly aligned
[ ] No spelling errors
[ ] Examples are tested and accurate
[ ] helm-docs content not manually edited (charts only)
Automated Validation¶
Future enhancements may include:
CI/CD link validation
PlantUML syntax checking
Terminology linting
Template compliance verification
Resources¶
Internal Resources¶
Main README: README.md
Contributing Guide: CONTRIBUTING.md
Code of Conduct: code-of-conduct.md
GitHub Copilot Instructions: .github/copilot-instructions.md
Use-Case Naming Conventions: usecase-library/use-case-naming-conventions.md
External Resources¶
Questions or Help¶
If you need assistance with documentation:
Check existing examples - Look at exemplar documentation listed in writing-style.md
Use the
@docsagent - Invoke with your questionReview templates - See templates/README.md
Ask in discussions - Open a GitHub discussion
Create an issue - Use the
documentationlabel
This documentation infrastructure helps maintain high-quality, consistent documentation across the ODA Canvas project. Contribute improvements to make it even better!