alumni_lookup

Documentation Standards & Templates

Purpose: Ensure consistent, organized, and up-to-date documentation across the project.
Audience: AI coding agents (GitHub Copilot, Claude, etc.) and human developers.

This document defines standards for creating and maintaining documentation. AI agents should reference this when creating new feature docs, bug fix notes, or updating existing documentation.

Documentation Principles

Single Source of Truth — Each concept should be documented in ONE place
Keep Current — Update docs during development, not after
Cross-Reference — Link related docs rather than duplicating content
Actionable — Include code examples and step-by-step instructions

Documentation Structure

Folder	Purpose	When to Update
`docs/` (root)	High-level overviews, changelog	Major releases, stakeholder docs
`docs/development/`	Technical guides for contributors	Architecture changes, new patterns
`docs/features/`	Feature-specific documentation	New features, feature changes
`docs/deployment/`	Production setup and operations	Infrastructure changes
`docs/planning/`	Future development specs	Planning phases only

Templates for New Documentation

This section provides templates for documenting new features and bug fixes.

🆕 New Feature Documentation Template

Basic Feature Template

# [Feature Name]

## 📋 Overview
Brief description of what this feature does and why it was needed.

## 🎯 Implementation Details
- **Models affected:** List any new or modified models
- **Controllers:** List affected controllers and new endpoints
- **Views:** Describe UI changes and new templates
- **Database changes:** List migrations and new tables/columns

## 🔧 Configuration
- **Environment variables:** List any new config requirements
- **Dependencies:** Note new gems or external services
- **Setup steps:** Any additional setup required

## 🚀 Usage
Step-by-step guide on how to use the feature.

## 🧪 Testing
- **Test files:** Location of test files
- **Test data:** Any special test data requirements
- **Manual testing:** Steps to manually verify the feature

## 🔍 Troubleshooting
Common issues and their solutions.

## 🔗 Related Documentation
Links to related docs and external resources.

Complex Feature Template (with Model Changes)

# [Feature Name]

## 📋 Overview
[Description]

## 🗃️ Database Changes
### New Tables
- `table_name`: Description of purpose
  - `column_name`: Description and data type
  
### Modified Tables
- `existing_table`: Changes made
  - Added: `new_column`
  - Modified: `existing_column`

### New Associations
- `ModelA belongs_to :model_b`
- `ModelB has_many :model_as`

## 🔗 Model Relationships
Update `docs/development/MODEL_RELATIONSHIPS.md` with:
- New association definitions
- Join patterns for queries
- Common query examples

## [Continue with other sections...]

🐛 Bug Fix Documentation Template

Basic Bug Fix Template

# Bug Fix: [Brief Description]

## 🚨 Issue Description
- **Error message:** `Exact error text`
- **Symptoms:** What the user experienced
- **Affected areas:** What parts of the app were broken

## 🔍 Root Cause
Technical explanation of what caused the bug.

## ✅ Solution
- **Changes made:** List of files modified
- **Code changes:** Key code snippets showing the fix
- **Reasoning:** Why this approach was chosen

## 🧪 Verification
- **Test cases:** How to verify the fix works
- **Edge cases:** Additional scenarios tested
- **Regression prevention:** How to avoid this bug in the future

## 📚 Documentation Updates
- **Debugging guides:** What was added to help future debugging
- **Model relationships:** Any association corrections documented
- **Best practices:** New guidelines to prevent similar issues

ActiveRecord Association Bug Fix Template

# Bug Fix: ActiveRecord Association Error

## 🚨 Issue Description
- **Error:** `ActiveRecord::ConfigurationError: Can't join 'Model' to association named 'wrong_name'`
- **Location:** Controller/model where error occurred
- **Impact:** What functionality was broken

## 🔍 Root Cause Analysis
### Incorrect Association Name
```ruby
# ❌ Wrong
Model.joins(:wrong_association_name)

# ✅ Correct  
Model.joins(:correct_association_name)

Missing Association Chain

# ❌ Wrong - skips intermediate model
Model.joins(parent: :grandparent)

# ✅ Correct - includes full chain
Model.joins(parent: { child: :grandparent })

✅ Solution Applied

File: app/controllers/example_controller.rb
Change: Corrected association name from :alumnus to :alumni
Additional fixes: Updated all related join queries

📚 Documentation Updates

Added to docs/development/MODEL_RELATIONSHIPS.md:
- Correct association definitions
- Common join patterns
- Error examples with solutions
Updated debugging section in docs/development/AGENTS.md
Enhanced error troubleshooting guides

🧪 Testing

# Verify association works in Rails console
Model.joins(:correct_association).count

🔒 Prevention

Always reference MODEL_RELATIONSHIPS.md before writing joins
Use Rails console to test associations before implementation
Include association tests in test suite ```

📋 Documentation Checklist

Use this checklist for every feature or bug fix:

✅ Feature Development Checklist

Create feature documentation in docs/features/
Update docs/development/MODEL_RELATIONSHIPS.md if models changed
Add setup instructions if configuration required
Include troubleshooting section
Update docs/README.md with links to new docs
Cross-reference related documentation

✅ Bug Fix Checklist

Document error message and root cause
Add solution to appropriate debugging guide
Update model relationships if associations fixed
Include prevention strategies
Add testing/verification steps
Enhance existing troubleshooting guides

✅ General Documentation Standards

Clear, actionable language used
Code examples included where relevant
Cross-references to related docs added
Searchable headings and keywords used
Contact/maintenance info included

Usage: Copy the appropriate template above when documenting new work, then customize for your specific feature or bug fix.