dpsifr
b0ba4f185d
- **Storage**: Removed redundant storage implementation files from `/storage` directory while retaining necessary `baseStorage.ts`. Verified no impact on functionality with passing tests. - **Documentation**: Consolidated multiple overlapping `.md` files into a single `statistics.md` file. Added structured sections for easier reference. Applied markdown naming conventions for clarity. - **Project**: Introduced `CHANGES_SUMMARY.md` and `MARKDOWN_CONVENTIONS.md` to document changes and naming guidelines, improving project organization. Updated `demo.md` file naming for consistency. **Purpose**: Simplify the codebase by removing duplicates, enhance maintainability through consolidated and structured documentation, and improve developer experience with clear guidelines and better organization.
67 lines
No EOL
1.9 KiB
Markdown
67 lines
No EOL
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: `scalingStrategy.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)
|
|
|
|
- scalingStrategy.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. |