Documentation Maintenance Guidelines

Overview

This document defines when and how developers and product should update documentation in @attunelogic-docs, with a focus on Feature Status docs under docs/developer/features/.

The goal is to keep docs aligned with what is actually implemented today across:

• @attunelogic-api
• @attunelogic-service
• @attunelogic-mobile

When to Update Docs

You must update docs in these situations:

1. New feature or module
   • Add a new Feature Status doc under docs/developer/features/ following:
     • features/feature-status-template.md.
   • Link it in:
     • Developer sidebar (e.g., under “🚛 Trucking Features” or an equivalent category).
2. Meaningful behavior change
   • When a feature’s behavior changes in a way users will notice (API contract, UX, roles, config), update:
     • The relevant Feature Status doc.
     • Any affected API or development docs (e.g., api/core-features, development/job-management).
3. Roadmap status changes
   • When a planned item moves from ❌ Not Started → 🚧 In Progress → ✅ Completed in any MASTER_ROADMAP.md:
     • Ensure the matching Feature Status doc reflects the new current state.
4. Deprecation or removal
   • When removing or deprecating a feature:
     • Mark it as deprecated in the Feature Status doc and relevant API docs.
     • Note any replacement workflows or migration steps.

Feature Status Docs – Expectations

Feature Status docs are current-state, implementation-focused docs:

• Should answer “what do we actually have in production today?”, per feature.
• Should not be speculative design documents.
• Should link to:
  • Roadmap items (for future work).
  • API/development docs (for detailed contracts/examples).

When editing a feature or creating a new one, ensure the corresponding Feature Status doc:

• Lists key models/controllers/routes (API).
• Lists key pages/components/hooks (Service & Mobile).
• Summarizes:
  • Implemented behavior.
  • Partial implementations.
  • Missing/not implemented items.

PR Checklist (for Developers)

For any PR that adds or significantly changes a feature, confirm:

1. Docs updated?
   • Relevant Feature Status doc updated or created.
   • Any affected API/development docs updated (if routes/contracts changed).
2. Links & sidebars?
   • New docs added to the appropriate sidebar category.
3. Roadmap alignment?
   • If a roadmap item is now completed or meaningfully advanced, update the relevant MASTER_ROADMAP.md.

You can add a short section to PR descriptions:

Docs:
- Updated: docs/developer/features/<feature>.md
- Updated: docs/developer/api/<api-page>.md (if applicable)

Ownership & Review

• Engineering:
  • Responsible for keeping technical sections accurate (models, controllers, routes, flows).
• Product / Domain Owners:
  • Responsible for validating business descriptions, “what this feature solves”, and roadmap links.
• Docs / Platform (if applicable):
  • Responsible for structure, clarity, and consistency across docs.

For major features, involve both engineering and product in the review of Feature Status docs.

Where to Add New Feature Docs

• Developer-facing Feature Status docs:
  • docs/developer/features/<feature-name>.md
• Customer-facing overviews (optional, higher-level language):
  • docs/customer/industry-guides/<industry>-<feature>.md

Use features/feature-status-template.md as the starting point for developer-facing docs.

Examples

Current trucking-focused Feature Status docs:

• features/trucking-loads-and-legs.md
• features/trucking-dispatch-scheduler.md
• features/trucking-quotes-and-proposals.md
• features/mobile-trucking-driver-experience.md

These serve as examples for future feature docs in other domains (service/repair, notifications, equipment, etc.).