Documentation Improvements

[alanbem]

Overview

The current documentation has several gaps between the implemented functionality and what is documented. This issue outlines areas that need documentation updates or additions to fully cover the framework's capabilities.

Key Areas Requiring Documentation

1. Event Store & Storage

• Document Redis storage implementation
• Add section on implementing custom storage backends
• Expand concurrency control documentation
  • Version-based optimistic locking
  • Handling ConcurrentWriteDetected exceptions
  • Best practices for conflict resolution
• Add schema management documentation
  • Required PostgreSQL schema structure
  • Migration handling
  • Schemable interface usage

2. Snapshotting System

• Create new documentation section for snapshotting
  • Snapshottable interface implementation
  • Available storage options (PostgreSQL, Redis, In-Memory)
  • Configuration and setup
  • Best practices for snapshot frequency
  • Performance considerations

3. Infrastructure Components

• Document Unit of Work pattern
  • Base UnitOfWork implementation
  • SnapshottingUnitOfWork functionality
  • Transaction handling
  • Integration with event publishing
• Add serialization documentation
  • Available serializers
  • Custom serializer implementation
  • Handling complex object graphs
• Document testing utilities
  • TestCase usage
  • Scenario class capabilities
  • Common testing patterns

4. Event Handling & Integration

• Expand event bus documentation
  • Event listener registration
  • Notification patterns
  • Integration with PublishingEventStore
• Add performance optimization guide
  • Large event stream handling
  • Snapshot optimization
  • Query optimization
• Create error handling guide
  • Common exception scenarios
  • Recovery patterns
  • Error handling best practices

5. Framework Integration

• Enhance Symfony bundle documentation
  • Service configuration
  • Common integration patterns
  • Environment-specific setup
• Add external system integration guides
  • Event store integration patterns
  • Event versioning strategies
  • Schema evolution handling

Implementation Examples Needed

• Add real-world usage examples for:
  • Custom event store implementation
  • Snapshot configuration
  • Error handling scenarios
  • Testing patterns
  • Performance optimization

Technical Details

The documentation should be added to the following locations:

• /docs/core-concepts/ - For fundamental concepts
• /docs/tutorials/ - For practical implementation guides
• /docs/symfony-bundle/ - For framework integration

Acceptance Criteria

• Documentation matches current implementation features
• All interfaces and important classes are documented
• Examples provided for common use cases
• Clear upgrade and migration guides included
• Testing and debugging guides provided
• Performance optimization guidelines documented

Additional Notes

• Current documentation size varies significantly between topics (e.g., Projections: 22KB vs Events: 3.4KB)
• Some core features like snapshotting are completely undocumented
• Need to maintain consistency in documentation style and depth across all sections