brainy/docs/MARKDOWN_FILE_MANAGEMENT.md

# Markdown File Management Guidelines

## Overview

This document establishes standards for managing .md files in the Brainy project to maintain a clean, organized, and professional documentation structure.

## Root Directory Standards

The project root should contain **only** these essential .md files:

### Required Files (GitHub/NPM Standards)
- `README.md` - Main project documentation and entry point
- `CHANGELOG.md` - Version history and release notes
- `CODE_OF_CONDUCT.md` - Community guidelines
- `CONTRIBUTING.md` - Contribution guidelines
- `LICENSE` - Legal license file (not .md but related)

### Prohibited in Root
❌ **Never place these in root:**
- Temporary summary files (e.g., `IMPLEMENTATION_SUMMARY.md`)
- Fix-related documentation (e.g., `RELIABILITY_IMPROVEMENTS_SUMMARY.md`)
- Organizational notes (e.g., `SCRIPT_ORGANIZATION_SOLUTION.md`)
- Update logs (e.g., `README_updates.md`, `changes-summary.md`)
- Environment-specific guides (should go in docs/)

## Documentation Organization Structure

```
docs/
├── COMPATIBILITY.md              # Cross-platform compatibility info
├── DOCUMENTATION_ORGANIZATION.md # This file's organization guide
├── development/                  # Developer-focused documentation
│   ├── DEVELOPERS.md
│   ├── DOCUMENTATION_STANDARDS.md
│   └── MARKDOWN_CONVENTIONS.md
├── guides/                       # User guides and tutorials
│   ├── cache-configuration.md
│   ├── model-management.md
│   └── production-migration-guide.md
└── technical/                    # Technical implementation details
    ├── TESTING.md               # Comprehensive testing guide
    ├── ENVIRONMENT_TESTING.md   # Environment-specific testing
    ├── CONCURRENCY_ANALYSIS.md
    └── STORAGE_TESTING.md
```

## File Naming Conventions

### Use UPPERCASE for Major Documents
- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`
- `TESTING.md`, `COMPATIBILITY.md`

### Use lowercase-with-hyphens for Specific Guides
- `cache-configuration.md`
- `model-management.md`
- `production-migration-guide.md`

### Use Descriptive Names
✅ **Good:**
- `ENVIRONMENT_TESTING.md` (specific purpose)
- `cache-configuration.md` (clear topic)
- `production-migration-guide.md` (clear audience and purpose)

❌ **Bad:**
- `IMPLEMENTATION_SUMMARY.md` (temporary)
- `changes-summary.md` (temporary)
- `notes.md` (vague)

## File Lifecycle Management

### Temporary Files
**Rule: Temporary files should be deleted immediately after their purpose is fulfilled.**

Examples of temporary files that should be deleted:
- Implementation summaries after feature completion
- Fix documentation after issues are resolved
- Organizational notes after reorganization is complete
- Update logs after updates are integrated

### Permanent Documentation
Files that should be maintained long-term:
- User guides and tutorials
- Technical reference documentation
- API documentation
- Testing guides
- Development standards

## Where to Place Different Types of Documentation

### Root Directory
- Only essential project files (README, CHANGELOG, etc.)

### docs/development/
- Developer setup guides
- Build instructions
- Code standards
- Documentation standards

### docs/guides/
- User tutorials
- Configuration guides
- Migration guides
- How-to documentation

### docs/technical/
- Technical implementation details
- Architecture documentation
- Testing documentation
- Performance analysis

### Package-Specific
- Each package (cli-package/, web-service-package/, etc.) should have its own README.md
- Package-specific documentation stays with the package

## Review Process

### Before Adding New .md Files
1. **Determine if it's temporary or permanent**
   - Temporary: Consider using issues, PRs, or comments instead
   - Permanent: Proceed with proper placement

2. **Choose the correct location**
   - Root: Only for essential project files
   - docs/: For all other documentation

3. **Use proper naming conventions**
   - Descriptive names that indicate purpose
   - Consistent with existing patterns

### Regular Cleanup
- Review .md files quarterly
- Delete temporary files that have served their purpose
- Consolidate duplicate or overlapping documentation
- Update links when files are moved

## Migration Guidelines

When reorganizing existing documentation:

1. **Categorize existing files**
   - Essential (keep in root)
   - Useful (move to docs/)
   - Temporary (delete)

2. **Update references**
   - Search for links to moved files
   - Update README.md and other documentation
   - Test that all links work

3. **Maintain backward compatibility when possible**
   - Consider redirects for important moved files
   - Update package.json scripts if they reference moved files

## Enforcement

### Code Review Checklist
- [ ] New .md files are in appropriate locations
- [ ] Temporary files are not being committed
- [ ] Links to documentation are correct
- [ ] File names follow conventions

### Automated Checks (Future)
Consider implementing:
- Linting rules for .md file placement
- Link checking in CI/CD
- Automated cleanup of temporary files

## Examples

### ✅ Good Documentation Structure
```
README.md                    # Main project docs
CHANGELOG.md                 # Version history
docs/guides/setup.md         # User guide
docs/technical/api.md        # Technical reference
```

### ❌ Bad Documentation Structure
```
README.md
IMPLEMENTATION_SUMMARY.md    # Temporary - should be deleted
FIX_NOTES.md                # Temporary - should be deleted
setup.md                    # Should be in docs/guides/
```

## Summary

Following these guidelines ensures:
- Clean, professional project structure
- Easy navigation for users and contributors
- Reduced maintenance overhead
- Consistent documentation organization
- Better discoverability of information

**Remember: When in doubt, ask "Is this temporary or permanent?" and "Who is the audience?" to determine the right approach.**