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: `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.
|