gh-greyhaven-ai-claude-code…/skills/ontological-documentation/reference/documentation_templates.md

# Ontological Documentation Templates

This document provides standardized templates for creating comprehensive ontological documentation for software systems.

## Core Documentation Templates

### 1. Concept Definition Template

```markdown
# [Concept Name]

## Quick Reference
- **Type**: [Entity/Value Object/Service/Repository/etc.]
- **Category**: [Domain/Business/Infrastructure/etc.]
- **Status**: [Active/Deprecated/Experimental]
- **Owner**: [Team/Person responsible]

## Definition
[Clear, concise definition of the concept. What is it? What purpose does it serve?]

## Purpose and Scope
**Why this concept exists:**
- [Problem it solves]
- [Business requirement it addresses]
- [Technical necessity]

**Scope and Boundaries:**
- [What's included]
- [What's excluded]
- [Related but separate concepts]

## Characteristics
### Essential Properties
- **Property 1**: [Description] - [Type] - [Constraints]
- **Property 2**: [Description] - [Type] - [Constraints]

### Behavioral Aspects
- **Action 1**: [Description] - [Preconditions] - [Postconditions]
- **Action 2**: [Description] - [Preconditions] - [Postconditions]

### Constraints and Rules
- [Business rule 1]
- [Validation rule 2]
- [Integrity constraint 3]

## Relationships

### Hierarchical Relationships
- **Is-A**: [Parent Concept] - [Rationale]
- **Has-A**: [Child Components] - [Composition details]

### Dependency Relationships
- **Depends-On**: [Required Concept] - [Dependency type]
- **Required-By**: [Dependent Concept] - [Usage context]

### Association Relationships
- **Associates-With**: [Related Concept] - [Nature of association]
- **Similar-To**: [Analogous Concept] - [Comparison points]

## Implementation

### Code Representation
```python
# Example implementation
class [ConceptName]:
    def __init__(self):
        self.property1 = None
        self.property2 = None
```

### Data Structure
- **Storage Format**: [Database table, JSON, etc.]
- **Serialization**: [How it's represented in API/transport]
- **Persistence**: [Where and how it's stored]

### Lifecycle
- **Creation**: [How instances are created]
- **Evolution**: [How instances change over time]
- **Deletion**: [How instances are removed]

## Examples

### Concrete Examples
1. **Example 1**: [Specific instance with explanation]
   - [Context]
   - [Properties]
   - [Behavior]

2. **Example 2**: [Another specific instance]
   - [Context]
   - [Properties]
   - [Behavior]

### Usage Patterns
- **Pattern 1**: [Common usage scenario]
- **Pattern 2**: [Another usage scenario]

## Evolution and History
- **Created**: [Date] - [Initial reason]
- **Major Changes**: [Change history]
- **Future Roadmap**: [Planned modifications]

## Related Documentation
- [Link to related concepts]
- [Link to implementation details]
- [Link to API documentation]
- [Link to user documentation]
```

### 2. Relationship Documentation Template

```markdown
# [Relationship Type]: [Source Concept] → [Target Concept]

## Relationship Overview
- **Type**: [Is-A/Part-Of/Depends-On/Associates-With/etc.]
- **Source**: [Source Concept Name]
- **Target**: [Target Concept Name]
- **Strength**: [Strong/Medium/Weak]
- **Direction**: [Unidirectional/Bidirectional]

## Definition
[Clear explanation of what this relationship means in the domain context]

## Rationale
**Why this relationship exists:**
- [Business reason]
- [Technical necessity]
- [Domain modeling decision]

## Characteristics

### Cardinality
- **Source → Target**: [One-to-One/One-to-Many/Many-to-Many]
- **Minimum**: [Required/Optional - specify minimum]
- **Maximum**: [Unbounded/Specific limit]

### Constraints
- **Existence Constraint**: [Rules about when relationship can exist]
- **Deletion Constraint**: [What happens when one end is deleted]
- **Update Constraint**: [How relationship changes are handled]

### Semantic Properties
- **Transitivity**: [Whether relationship is transitive]
- **Symmetry**: [Whether relationship is symmetric]
- **Reflexivity**: [Whether relationship is reflexive]

## Implementation

### Code Representation
```python
# Example implementation
class SourceConcept:
    def __init__(self):
        self.target_concepts = []  # Relationship implementation
```

### Data Modeling
- **Foreign Keys**: [How relationship is stored in database]
- **Join Tables**: [If applicable, for many-to-many relationships]
- **Indexing**: [Performance considerations]

### API Representation
- **REST Endpoints**: [How relationship is exposed in API]
- **GraphQL Schema**: [How relationship appears in GraphQL]
- **Serialization**: [How relationship is represented in JSON/XML]

## Examples

### Example Instances
1. **Example 1**: [Specific relationship instance]
   - **Source Instance**: [Details]
   - **Target Instance**: [Details]
   - **Context**: [When and why this exists]

2. **Example 2**: [Another specific instance]
   - **Source Instance**: [Details]
   - **Target Instance**: [Details]
   - **Context**: [When and why this exists]

### Usage Patterns
- **Creation Pattern**: [How relationships are established]
- **Query Pattern**: [How relationships are accessed]
- **Modification Pattern**: [How relationships are changed]

## Validation Rules

### Business Rules
- [Rule 1]: [Description and validation logic]
- [Rule 2]: [Description and validation logic]

### Technical Constraints
- [Constraint 1]: [Technical limitation or requirement]
- [Constraint 2]: [Performance or scalability consideration]

## Related Documentation
- [Source Concept Documentation]
- [Target Concept Documentation]
- [Related Relationships]
- [Implementation Details]
```

### 3. Domain Model Overview Template

```markdown
# [Domain Name] Domain Model

## Executive Summary
[Brief overview of the domain and its core concepts]

## Core Concepts Map
[Visual representation or hierarchical list of main concepts]

### Primary Entities
- **[Entity 1]**: [Brief description]
- **[Entity 2]**: [Brief description]
- **[Entity 3]**: [Brief description]

### Supporting Concepts
- **[Value Object 1]**: [Brief description]
- **[Service 1]**: [Brief description]
- **[Repository 1]**: [Brief description]

## Concept Hierarchy

```
[Top-level concepts]
├── [Category 1]
│   ├── [Sub-concept 1.1]
│   ├── [Sub-concept 1.2]
│   └── [Sub-concept 1.3]
├── [Category 2]
│   ├── [Sub-concept 2.1]
│   └── [Sub-concept 2.2]
└── [Category 3]
    ├── [Sub-concept 3.1]
    └── [Sub-concept 3.2]
```

## Key Relationships

### Critical Relationships
1. **[Relationship 1]**: [Source] → [Target]
   - [Importance and impact]
   - [Business significance]

2. **[Relationship 2]**: [Source] → [Target]
   - [Importance and impact]
   - [Business significance]

### Relationship Patterns
- **Composition Pattern**: [Description]
- **Dependency Pattern**: [Description]
- **Association Pattern**: [Description]

## Business Rules and Constraints

### Domain Rules
1. **[Rule 1]**: [Description] - [Impact]
2. **[Rule 2]**: [Description] - [Impact]

### Invariants
- **Invariant 1**: [What must always be true]
- **Invariant 2**: [What must always be true]

## Processes and Workflows

### Core Business Processes
1. **[Process 1]**
   - **Trigger**: [What starts the process]
   - **Steps**: [Sequence of actions]
   - **Actors**: [Who/what participates]
   - **Outcomes**: [Results and side effects]

2. **[Process 2]**
   - **Trigger**: [What starts the process]
   - **Steps**: [Sequence of actions]
   - **Actors**: [Who/what participates]
   - **Outcomes**: [Results and side effects]

### State Machines
- **[Entity 1] States**: [State transitions and conditions]
- **[Entity 2] States**: [State transitions and conditions]

## Integration Points

### External Systems
- **[System 1]**: [Integration type and purpose]
- **[System 2]**: [Integration type and purpose]

### Data Flows
- **Inbound Data**: [What data comes from where]
- **Outbound Data**: [What data goes to where]

## Evolution Strategy

### Current State
- [Description of current domain model state]

### Planned Changes
- **[Change 1]**: [Description and timeline]
- **[Change 2]**: [Description and timeline]

### Migration Strategy
- [How to transition from current to future state]

## Quality Metrics

### Model Health
- **Complexity**: [Assessment of model complexity]
- **Consistency**: [How consistent the model is]
- **Completeness**: [Gaps and coverage]

### Usage Metrics
- **Most Used Concepts**: [Statistics on concept usage]
- **Relationship Density**: [How interconnected concepts are]
- **Change Frequency**: [How often concepts change]

## Related Documentation
- [Link to detailed concept documentation]
- [Link to API documentation]
- [Link to business requirements]
- [Link to technical architecture]
```

### 4. Ontology Change Log Template

```markdown
# Ontology Change Log

## Version [Version Number] - [Date]

### Summary
[Brief overview of changes in this version]

### Added Concepts
- **[Concept Name]**: [Reason for addition] - [Impact]
- **[Concept Name]**: [Reason for addition] - [Impact]

### Modified Concepts
- **[Concept Name]**: [Changes made] - [Reason for change] - [Impact]
- **[Concept Name]**: [Changes made] - [Reason for change] - [Impact]

### Removed Concepts
- **[Concept Name]**: [Reason for removal] - [Migration strategy]

### Added Relationships
- **[Relationship]**: [Source] → [Target] - [Reason]

### Modified Relationships
- **[Relationship]**: [Source] → [Target] - [Changes] - [Reason]

### Removed Relationships
- **[Relationship]**: [Source] → [Target] - [Reason] - [Impact]

### Breaking Changes
- **[Change Description]**: [Impact on dependent systems] - [Migration required]

### Migration Guide
[Step-by-step guide for adapting to these changes]

## Previous Versions
[Link to previous change logs]
```

## Specialized Templates

### API Ontology Template
```markdown
# [API Name] Ontology

## Resource Model
[List of all resources and their relationships]

## Semantic Operations
[CRUD operations and their domain meanings]

## Media Types
[Content types and their semantic significance]

## Hypermedia Controls
[HATEOAS relationships and link semantics]
```

### Database Schema Ontology Template
```markdown
# [Database Name] Schema Ontology

## Table Concepts
[Tables as domain concepts]

## Column Semantics
[Columns as concept properties]

## Constraint Logic
[Constraints as business rules]

## Trigger Semantics
[Triggers as automated processes]
```

### Event-Driven Architecture Ontology Template
```markdown
# [System Name] Event Ontology

## Event Taxonomy
[Categorization of all events]

## Event Relationships
[Causal and temporal relationships]

## Event Semantics
[Meaning and significance of events]

## Process Integration
[How events drive business processes]
```

## Template Usage Guidelines

### When to Use Each Template

1. **Concept Definition**: Use for every significant domain concept
2. **Relationship Documentation**: Use for critical or complex relationships
3. **Domain Model Overview**: Use for bounded contexts or major domains
4. **Change Log**: Use for every ontology modification
5. **Specialized Templates**: Use for specific architectural patterns

### Quality Checklist

For each documentation entry:
- [ ] Definition is clear and unambiguous
- [ ] Purpose and scope are well-defined
- [ ] Relationships are accurately described
- [ ] Examples are relevant and illustrative
- [ ] Implementation details are correct
- [ ] Related documentation is linked
- [ ] Review date is recorded
- [ ] Owner is identified

### Review Process

1. **Self-Review**: Check completeness and accuracy
2. **Peer Review**: Get feedback from other developers
3. **Domain Expert Review**: Validate with domain experts
4. **Architecture Review**: Ensure alignment with system architecture
5. **Documentation Review**: Check for clarity and usability