platform/doc/CONTRIBUTING.md

Contributing to Framework Documentation

Overview

This guide explains how to contribute to our framework documentation. We maintain comprehensive documentation covering package specifications, gap analyses, integration guides, and architectural documentation.

Documentation Structure

Core Documentation

1. Getting Started Guide - Framework introduction and setup
2. Laravel Compatibility Roadmap - Implementation timeline
3. Foundation Integration Guide - Integration patterns
4. Testing Guide - Testing approaches
5. Package Integration Map - Package relationships

Core Architecture

1. Core Architecture - System design and patterns
2. Core Package Specification - Core implementation

Package Documentation

Each package has:

1. Package Specification - Implementation details
2. Gap Analysis - Laravel compatibility gaps
3. Integration Guide - Package integration patterns
4. Development Guidelines - Implementation standards

Contribution Guidelines

1. Documentation Standards

File Naming

• Use lowercase with underscores
• End with .md extension
• Be descriptive and specific
• Examples:
  • package_specification.md
  • gap_analysis.md
  • integration_guide.md

File Structure

• Start with # Title
• Include Overview section
• Add Related Documentation links
• Use clear section headers
• Include code examples
• End with development guidelines

Content Requirements

• No placeholders or truncation
• Complete code examples
• Clear cross-references
• Proper markdown formatting
• Comprehensive coverage

2. Writing Style

Technical Writing

• Be clear and concise
• Use active voice
• Write in present tense
• Focus on technical accuracy
• Include practical examples

Code Examples

// Include complete, working examples
class Example {
  final String name;
  
  Example(this.name);
  
  void demonstrate() {
    print('Demonstrating: $name');
  }
}

// Show usage
var example = Example('feature');
example.demonstrate();

Cross-References

• Use relative links
• Link to related docs
• Reference specific sections
• Example:

  See [Container Integration](container_package_specification.md#integration) for details.
  

3. Documentation Types

Package Specification

• Implementation details
• API documentation
• Integration examples
• Testing guidelines
• Development workflow

Gap Analysis

• Current implementation
• Laravel features
• Missing functionality
• Implementation plan
• Priority order

Integration Guide

• Integration points
• Package dependencies
• Code examples
• Best practices
• Common patterns

4. Review Process

Before Submitting

1. Check content completeness
2. Verify code examples
3. Test all links
4. Run markdown linter
5. Review formatting

Pull Request

1. Clear description
2. Reference related issues
3. List documentation changes
4. Include review checklist
5. Add relevant labels

Review Checklist

• No placeholders or truncation
• Complete code examples
• Working cross-references
• Proper formatting
• Technical accuracy

5. Development Workflow

Creating Documentation

1. Create feature branch
2. Write documentation
3. Add code examples
4. Include cross-references
5. Submit pull request

Updating Documentation

1. Review existing content
2. Make necessary changes
3. Update related docs
4. Verify all links
5. Submit pull request

Review Process

1. Technical review
2. Style review
3. Code example review
4. Cross-reference check
5. Final approval

Style Guide

1. Markdown

Headers

# Main Title
## Section Title
### Subsection Title
#### Minor Section

Lists

1. Ordered Item
2. Ordered Item
   - Unordered Sub-item
   - Unordered Sub-item

- Unordered Item
- Unordered Item
  1. Ordered Sub-item
  2. Ordered Sub-item

Code Blocks

/// Code with syntax highlighting
```dart
class Example {
  void method() {
    // Implementation
  }
}

/// Inline code Use var for variable declaration.

#### Links
```markdown
[Link Text](relative/path/to/file.md)
[Link Text](relative/path/to/file.md#section)

2. Content Organization

Package Documentation

1. Overview
2. Core Features
3. Integration Examples
4. Testing
5. Development Guidelines

Gap Analysis

1. Overview
2. Missing Features
3. Implementation Gaps
4. Priority Order
5. Next Steps

Integration Guide

1. Overview
2. Integration Points
3. Code Examples
4. Best Practices
5. Development Guidelines

3. Code Examples

Complete Examples

// Include all necessary imports
import 'package:framework/core.dart';

// Show complete implementation
class ServiceProvider {
  final Container container;
  
  ServiceProvider(this.container);
  
  void register() {
    container.singleton<Service>((c) => 
      ServiceImplementation()
    );
  }
}

// Demonstrate usage
void main() {
  var container = Container();
  var provider = ServiceProvider(container);
  provider.register();
}

Integration Examples

// Show real integration scenarios
class UserService {
  final EventDispatcher events;
  final Database db;
  
  UserService(this.events, this.db);
  
  Future<void> createUser(User user) async {
    await events.dispatch(UserCreating(user));
    await db.users.insert(user);
    await events.dispatch(UserCreated(user));
  }
}

Questions?

For questions or clarification:

1. Review existing documentation
2. Check style guide
3. Ask in pull request
4. Update guidelines as needed