feat(docs): add comprehensive user guides and installation instructions for Brainy

2025-08-03 17:33:52 -07:00 · 2025-08-03 17:33:52 -07:00 · 5799a79f0c
commit 5799a79f0c
parent c92eeae234
15 changed files with 1859 additions and 1 deletions
--- a/docs/archive/DOCUMENTATION_ORGANIZATION.md
+++ b/docs/archive/DOCUMENTATION_ORGANIZATION.md
@ -0,0 +1,122 @@
+# Documentation Organization
+
+This document explains the new documentation structure and workflow for managing markdown files in the Brainy project.
+
+## Overview
+
+The documentation has been reorganized from 29 scattered markdown files at the root level to a clean, organized structure with only essential files at the root and categorized documentation in the `docs/` directory.
+
+## New Structure
+
+### Root Level Files (GitHub/NPM Standards)
+- `README.md` - Main project documentation
+- `CONTRIBUTING.md` - Contribution guidelines  
+- `CODE_OF_CONDUCT.md` - Community standards
+- `CHANGELOG.md` - Version history and release notes
+
+### Documentation Directory Structure
+```
+docs/
+├── technical/           # Technical documentation and analysis
+│   ├── CONCURRENCY_ANALYSIS.md
+│   ├── STORAGE_CONCURRENCY_ANALYSIS.md
+│   ├── THREADING.md
+│   ├── STATISTICS.md
+│   ├── TESTING.md
+│   ├── VITEST_IMPROVEMENTS.md
+│   ├── REALTIME_UPDATES.md
+│   ├── METADATA_HANDLING.md
+│   ├── VECTOR_DIMENSION_STANDARDIZATION.md
+│   ├── USE_MODEL_LOADING_EXPLANATION.md
+│   ├── STORAGE_TESTING.md
+│   ├── TECHNICAL_GUIDES.md
+│   ├── ENVIRONMENT_TESTING.md
+│   └── SCALING_STRATEGY.md
+├── development/         # Development and contributor documentation
+│   ├── DEVELOPERS.md
+│   ├── DOCUMENTATION_STANDARDS.md
+│   ├── MARKDOWN_CONVENTIONS.md
+│   ├── EXPECTED_TEST_MESSAGES.md
+│   └── PRETTY_TEST_REPORTER.md
+└── guides/             # User guides and migration documentation
+    ├── cache-configuration.md
+    ├── hnsw-field-search.md
+    ├── json-document-search.md
+    ├── model-management.md
+    ├── optional-model-bundling.md
+    ├── production-migration-guide.md
+    └── service-identification.md
+```
+
+
+## CHANGELOG.md Management
+
+### Automated Workflow
+
+The project now uses automated changelog management:
+
+1. **Adding Changes**: Add entries to the `[Unreleased]` section in `CHANGELOG.md`
+2. **Version Bumping**: Use npm scripts that automatically update the changelog:
+   - `npm run version:patch` - Patch version bump + changelog update
+   - `npm run version:minor` - Minor version bump + changelog update  
+   - `npm run version:major` - Major version bump + changelog update
+
+3. **Manual Updates**: Use `npm run changelog:update` to manually update the changelog
+
+### Changelog Format
+
+The changelog follows the [Keep a Changelog](https://keepachangelog.com/) standard:
+
+- **Added** - New features
+- **Changed** - Changes in existing functionality
+- **Deprecated** - Soon-to-be removed features
+- **Removed** - Now removed features
+- **Fixed** - Bug fixes
+- **Security** - Vulnerability fixes
+
+### GitHub Integration
+
+The CHANGELOG.md is automatically used for:
+- GitHub releases (via `scripts/create-github-release.js`)
+- NPM package release notes
+- Version history tracking
+
+## Benefits of New Structure
+
+1. **Clean Root Directory**: Only 4 essential markdown files at root level
+2. **Better Organization**: Logical categorization of documentation in docs/ subdirectories
+3. **GitHub Compliance**: Follows GitHub and NPM best practices
+4. **Automated Maintenance**: Changelog updates are automated
+5. **Easy Navigation**: Clear directory structure for different doc types
+6. **Reduced Clutter**: Temporary and outdated files have been removed
+
+## Workflow for Contributors
+
+### Adding Documentation
+1. **Technical docs** → `docs/technical/`
+2. **Development docs** → `docs/development/`
+3. **User guides** → `docs/guides/`
+4. **Temporary files** → Should be avoided; use issues or PRs for temporary documentation
+
+### Making Changes
+1. Add changes to `[Unreleased]` section in `CHANGELOG.md`
+2. Use appropriate category (Added, Changed, Fixed, etc.)
+3. When ready to release, use `npm run version:patch/minor/major`
+4. The changelog will be automatically updated with version and date
+
+### Release Process
+1. Ensure `[Unreleased]` section has all changes
+2. Run `npm run version:patch/minor/major`
+3. Run `npm run deploy` to publish and create GitHub release
+4. GitHub release will use CHANGELOG.md content
+
+## Migration Notes
+
+- All technical documentation organized in `docs/technical/`
+- Development documentation organized in `docs/development/`
+- User guides organized in `docs/guides/`
+- Temporary summary files and archived content have been cleaned up
+- Links in existing documentation may need updates
+- New automation ensures changelog stays current
+
+This reorganization provides a sustainable, scalable approach to documentation management that follows industry best practices and integrates seamlessly with GitHub and NPM workflows.
--- a/docs/archive/MARKDOWN_FILE_MANAGEMENT.md
+++ b/docs/archive/MARKDOWN_FILE_MANAGEMENT.md
@ -0,0 +1,195 @@
+# 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.**