Documentation Guidelines

This document outlines the guidelines for creating and maintaining documentation for the Family Shapes project. Following these guidelines ensures that our documentation is consistent, comprehensive, and accessible.

Documentation Structure

The Family Shapes project follows a structured approach to documentation:

/
├── README.md                 # Project overview, quick start guide, and links to detailed docs
├── CHANGELOG.md              # Chronological list of notable changes
├── ROADMAP.md                # Future development plans and milestones
├── docs/                     # Main documentation directory (single source of truth)
│   ├── index.md              # Documentation home page and navigation guide
│   ├── getting-started/      # Onboarding and setup guides
│   ├── architecture/         # System architecture documentation
│   ├── features/             # Detailed feature documentation
│   ├── development/          # Development guidelines and workflows
│   │   ├── database/         # Database-related documentation
│   │   ├── frontend/         # Frontend development guidelines
│   │   └── testing/          # Testing strategies and procedures
│   ├── deployment/           # Deployment procedures and environments
│   ├── api/                  # API documentation
│   └── contributing/         # Contribution guidelines

WIP Documents Policy

• In‑progress project or feature specifications should be placed at the root of DOCS/ (not inside subfolders) and use a title suffix WIP_ while under active development.
• When the work is completed, move the document to DOCS/historical/ and remove the WIP_ suffix from the title/frontmatter.
• Index files (DOCS/index.md and DOCS/README.md) should include links to any current WIP docs.

Documentation Standards

1. File Format and Structure

• All documentation should be written in Markdown format
• Use consistent headers (H1 for title, H2 for main sections, H3 for subsections)
• Include a table of contents for documents longer than 3 sections
• Use code blocks with appropriate language syntax highlighting
• Include a status indicator at the top of each document:
  • 🟢 STABLE - Well-established, unlikely to change
  • 🟡 EVOLVING - Subject to refinement and expansion
  • 🔴 DRAFT - Initial documentation, subject to significant changes
  • ⚠️ DEPRECATED - Will be removed or replaced

2. Document Metadata

Each document should include YAML front matter with:

---
title: Document Title
description: Brief description of the document's purpose
status: stable|evolving|draft|deprecated
lastUpdated: YYYY-MM-DD
owner: Team or individual responsible
---

3. Cross-Referencing

• Use relative links to reference other documentation files
• For code references, link to specific files or directories in the repository
• When referencing external resources, include the full URL and access date

Documentation Types

1. Project Documentation

Located in the /docs directory, this is the primary source of truth for all project information:

• Architecture Documentation: System design, component interactions, data flow
• Feature Documentation: Detailed descriptions of implemented features
• Development Guidelines: Coding standards, workflows, best practices
• API Documentation: Endpoints, parameters, response formats
• Deployment Documentation: Environment setup, deployment procedures

2. Repository Documentation

Located at the repository root, these files provide high-level information:

• README.md: Project overview, quick start guide, links to detailed docs
• CHANGELOG.md: Chronological record of notable changes
• ROADMAP.md: Future development plans and milestones

Documentation Workflow

1. Creating New Documentation

1. Identify the appropriate location based on the documentation type
   • If the document is a work‑in‑progress project/feature plan, create it at the root of DOCS/ with a WIP_ suffix in the title and link it from DOCS/index.md and DOCS/README.md.
2. Create a new Markdown file with the required metadata
3. Follow the structure and formatting guidelines
4. Add links to the new document from relevant existing documents
5. Update the documentation index if necessary

2. Updating Existing Documentation

1. Update the content following the established structure
2. Update the lastUpdated field in the metadata
3. Consider adding a change log entry within the document for significant changes
4. Update any cross-references affected by the changes

3. Deprecating Documentation

1. Mark the document as deprecated in the metadata
2. Add a notice at the top indicating why it's deprecated and what replaces it
3. Keep the document available until all references to it are updated

Changelog Management

The project maintains a structured changelog at /CHANGELOG.md following these principles:

1. Chronological Order: Most recent changes at the top
2. Version Grouping: Changes grouped by version number
3. Type Categorization: Changes categorized as:
   • Added: New features
   • Changed: Changes to existing functionality
   • Deprecated: Features that will be removed
   • Removed: Features that were removed
   • Fixed: Bug fixes
   • Security: Security-related changes
4. Date Tracking: Each version includes its release date
5. Reference Links: Links to relevant issues, PRs, or documentation

Example format:

# Changelog

All notable changes to this project will be documented in this file.

## [1.2.0] - 2025-09-15

### Added
- New donor portal with privacy controls
- Health tracking system for donors

### Changed
- Improved family tree visualization performance
- Enhanced organization management interface

### Fixed
- Connection loading issues on the family tree page
- User profile duplication bug

Roadmap Management

The project roadmap at /ROADMAP.md follows these principles:

1. Immediate Priorities: Clear section at the top highlighting the most urgent tasks
2. Phase Organization: Development organized into clear phases
3. Timeline Indicators: Approximate timeframes for each phase
4. Status Tracking: Current status of each planned feature
5. Priority Levels: Clear indication of feature priorities
6. Dependency Mapping: Dependencies between features
7. Key Milestones: Table showing major project milestones and their status

Example format:

# Development Roadmap

## 🚨 Immediate Priorities (Next 2 Weeks)

1. 🔴 **Fix Family Tree Permissions**: Implement proper role constraints
   - Due: End of Month
   - Owner: Database Team
   - Dependencies: None

2. 🔴 **Implement Three-Platform Architecture**: Complete separation of platforms
   - Due: Mid-next month
   - Owner: Architecture Team
   - Dependencies: None

## Key Milestones

| Milestone | Target Date | Status | Key Deliverables |
|-----------|-------------|--------|------------------|
| Database Architecture | Q3 2025 | 🚧 IN PROGRESS | Family Tree Permissions, Three-Platform Architecture |
| Enhanced Donor Portal | Q4 2025 | 📅 PLANNED | Advanced Privacy Controls, Health History Tracking |

## Current Phase: Database Architecture Refactoring (Q3 2025)

### In Progress
- 🚧 🔴 **Fix Family Tree Permissions**: Implement proper role constraints
- 🚧 🔴 **Implement Three-Platform Architecture**: Separate architecture for different user types

### Planned
- 📅 🔴 **Fix Sharing Links System**: Ensure sharing links work correctly
- 📅 🟡 **Rename Organizations to Communities**: Clarify terminology

Documentation Review Process

1. Regular Reviews: Documentation should be reviewed quarterly
2. Update Triggers: Documentation must be updated when:
   • New features are implemented
   • Existing features are significantly changed
   • Bugs related to documented features are fixed
   • Architecture or design decisions change
3. Accuracy Verification: Technical documentation should be verified by someone other than the author
4. Accessibility Check: Ensure documentation is understandable to the target audience

Best Practices

1. Keep Documentation Close to Code: Place documentation close to the code it describes
2. Update Documentation with Code Changes: Update documentation when making code changes
3. Use Examples: Include examples to illustrate concepts
4. Consider the Audience: Write for the intended audience (developers, users, etc.)
5. Be Concise: Keep documentation clear and to the point
6. Use Visual Aids: Include diagrams, screenshots, and other visual aids when helpful
7. Maintain Consistency: Use consistent terminology and formatting
8. Link to Related Documentation: Provide links to related documentation
9. Document Assumptions and Limitations: Clearly state any assumptions or limitations
10. Include Troubleshooting Information: Provide troubleshooting guidance for common issues