David Snelling
1539ba74de
- Deleted the following obsolete files: - `CHANGES.md`, `changes-summary.md`, `CHANGES_SUMMARY.md`: Contained redundant or outdated change logs and implementation summaries. - `COMPATIBILITY.md`: Detailed compatibility behavior no longer relevant after environment detection updates. - `fix-documentation.md`: Addressed a resolved issue regarding `process.memoryUsage` errors in testing. - `DIMENSION_MISMATCH_SUMMARY.md`: Provided a legacy summary of resolved embedding dimension mismatch issues. - `demo.md`: Documented an outdated demo process for testing Brainy features. - `CONCURRENCY_IMPLEMENTATION_SUMMARY.md`: Summarized already-documented concurrency features. - `IMPLEMENTATION_SUMMARY.md`: Detailed an obsolete implementation of optional model bundling. - Purpose: - Streamline and declutter archive by removing redundant or outdated documentation. - Align repository with current feature set and documentation standards.
67 lines
1.9 KiB
Markdown
67 lines
1.9 KiB
Markdown
# Markdown File Naming Conventions
|
|
|
|
This document outlines the naming conventions for markdown (.md) files in the Brainy project.
|
|
|
|
## Naming Patterns
|
|
|
|
Based on the current project structure, we follow these conventions for markdown files:
|
|
|
|
### Uppercase Naming
|
|
|
|
Use uppercase filenames for project-level documentation:
|
|
|
|
- README.md - Project overview and main documentation
|
|
- CONTRIBUTING.md - Contribution guidelines
|
|
- LICENSE.md - License information
|
|
- CHANGES.md - Changelog
|
|
- CODE_OF_CONDUCT.md - Code of conduct
|
|
- Other project-level documentation files
|
|
|
|
Examples: `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`
|
|
|
|
### Lowercase Naming
|
|
|
|
Use lowercase filenames for technical documentation and implementation details:
|
|
|
|
- Technical guides
|
|
- Implementation details
|
|
- Architecture documentation
|
|
- Specific feature documentation
|
|
|
|
Examples: `SCALING_STRATEGY.md`, `STATISTICS.md`
|
|
|
|
## Rationale
|
|
|
|
This convention makes it easy to distinguish between:
|
|
|
|
1. Project-level documentation that applies to the entire project and is relevant to all contributors and users (uppercase)
|
|
2. Technical documentation that focuses on specific implementation details and is primarily relevant to developers working on those features (lowercase)
|
|
|
|
## Recommendations
|
|
|
|
1. Continue using uppercase names for project-level documentation files
|
|
2. Continue using lowercase names for technical documentation files
|
|
3. Be consistent within each category
|
|
4. Always use `README.md` (uppercase) for directory-level documentation
|
|
|
|
## Examples
|
|
|
|
### Project-Level Documentation (Uppercase)
|
|
|
|
- README.md
|
|
- CONTRIBUTING.md
|
|
- LICENSE.md
|
|
- CHANGES.md
|
|
- CODE_OF_CONDUCT.md
|
|
- DEVELOPERS.md
|
|
- STORAGE_TESTING.md
|
|
- THREADING.md
|
|
|
|
### Technical Documentation (Lowercase)
|
|
|
|
- SCALING_STRATEGY.md
|
|
- statistics.md
|
|
- architecture.md
|
|
- implementation-details.md
|
|
|
|
By following these conventions, we maintain consistency and make it easier for contributors to find the right documentation.
|