soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions
brainy/docs/development/MARKDOWN_CONVENTIONS.md
David Snelling 79df44351c **chore: remove outdated changelog and summary documents** 
- Deleted `CHANGES.md`, `CHANGES_SUMMARY.md`, `CONCURRENCY_ANALYSIS.md`, `CONCURRENCY_IMPLEMENTATION_SUMMARY.md`, and related developer documentation files.
- Removed redundant or legacy content no longer aligned with the current codebase and workflows.
- Updated repository to reflect streamlined documentation approach, reducing clutter and improving maintainability.

**Purpose**: Simplify and declutter repository by removing obsolete documentation files, ensuring it remains focused and relevant.
2025-07-30 11:51:39 -07:00

1.9 KiB
Raw Blame History

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.