Documentation Guide

This guide defines how documentation is organized and managed in this project.

Last Updated: 2026-01-25

Directory Structure

docs/
├── DOCS_GUIDE.md              # This file
├── guides/                    # Development guides and standards
│   ├── INDEX.md
│   └── features/              # Feature-specific documentation
├── issues/                    # Active issues and errors
│   └── resolved/              # Resolved issues
└── plans/                     # Implementation plans
    ├── INDEX.md               # Main plans index
    ├── backlog/               # Planned but not yet active
    │   └── INDEX.md
    ├── archive/               # Completed plans
    ├── reports/               # Admin-facing completion reports
    │   └── INDEX.md
    └── templates/             # Plan and report templates
        ├── PLAN_TEMPLATE.md
        ├── PLAN_TEMPLATE_SIMPLE.md
        └── COMPLETION_REPORT_TEMPLATE.md

Plans

Lifecycle

Plans follow this workflow:

Backlog → Active → Archive
                 ↘ Report (for admin users)

Templates

Use templates from docs/plans/templates/:

Naming Convention

Plans are numbered sequentially: NNN-descriptive-name.md

Examples:

• 001-client-portal-plan.md
• 212-audit-system-improvements.md
• 212a-scoring-response-types.md (sub-plan)

Numbering

Run the script to get the next available plan number:

php scripts/util/get-next-plan-number.php

This scans docs/plans/, docs/plans/archive/, and docs/plans/backlog/ and returns the next number.

Workflow

Starting a new plan:

1. Choose appropriate template from docs/plans/templates/
2. Run php scripts/util/get-next-plan-number.php to get next number
3. Save to docs/plans/backlog/ if not starting immediately, or docs/plans/ if active

Activating a backlog plan:

1. Move file from docs/plans/backlog/ to docs/plans/
2. Update status to "In Progress"
3. Update INDEX files in both directories

Completing a plan:

1. Move file from docs/plans/ to docs/plans/archive/
2. Update status to "Complete"
3. Create completion report in docs/plans/reports/ (for significant features)
4. Update feature guide in docs/guides/features/
5. Commit changes

Completion Reports

Purpose

Completion reports are written for admin users, not developers. They explain:

• What's new and how to access it
• Step-by-step usage instructions
• Changes to existing workflows
• Known limitations

Location

docs/plans/reports/YYYY-MM-DD-feature-name.md

When to Create

Create a completion report for:

• New features visible to admin users
• Significant changes to existing functionality
• New settings or configuration options

Skip for:

• Internal refactoring
• Bug fixes
• Developer-only changes

Issues

Location

• Active issues: docs/issues/
• Resolved issues: docs/issues/resolved/

Naming Convention

Use descriptive kebab-case names: descriptive-issue-name.md

Examples:

• login-redirect-loop.md
• invoice-total-calculation-error.md

Lifecycle

1. Create issue in docs/issues/ when error/problem is encountered
2. Update issue as investigation and fixes progress
3. When resolved, move to docs/issues/resolved/

Issue Template

# Issue Title

## Description
Brief description of the issue.

## Steps to Reproduce
1. Step one
2. Step two

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Investigation Notes
Notes added during investigation.

## Resolution
How the issue was resolved (filled in when moving to resolved/).

Guides

Location

• Development guides: docs/guides/
• Feature guides: docs/guides/features/

Updating Guides

ALWAYS update the appropriate feature guide after implementing or modifying any feature:

1. Find existing guide in docs/guides/features/
2. If none exists, create one following existing format
3. Update docs/guides/features/INDEX.md
4. Update docs/guides/INDEX.md if adding new guide

General Guidelines

• Keep documentation concise and actionable
• Update docs as part of every task
• Commit documentation changes with related code changes
• Use markdown formatting consistently
• Always update INDEX files when adding/moving documents

Related Documentation

• Documentation Standards - Writing guidelines
• Plans Index - All plans
• Backlog Index - Planned features
• Guides Index - Development guides