gh-greyhaven-ai-claude-code-config-grey-haven-plugins-developer-experience/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

# [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

# 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

# [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

# [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

# [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