documentation-how

Documentation Update Procedures

For guidance on WHEN to update documentation, see the "Documentation Requirements (Always-On)" section in .github/copilot-instructions.md.

This guide covers the HOW: where to make changes and what to update for each type of modification.

Documentation Locations by Component

• Service Overview: docs/user-guide/microservices/<service>/<service>.md - Feature descriptions, API endpoints, usage examples
• Build Instructions: docs/user-guide/microservices/<service>/get-started/build-from-source.md - Build steps, Makefile targets, Docker commands
• Service README: <service>/README.md - Quick start and high-level overview (if exists)
• API Specifications: docs/user-guide/microservices/<service>/**/_assets/*.yaml or api-reference.md - API specs/references for REST APIs
• Root Documentation: docs/user-guide/ - Cross-service documentation, architecture guides
• Testing Guide: tests/README.md and service-specific test docs (for example mapping/tests/README.md) - Test setup and execution instructions

Documentation Update Checklist

When making changes, verify and update:

1. Feature descriptions in overview.md (list all options/variants)
2. Build commands in build-from-source.md (include new targets)
3. API documentation (if endpoints or parameters changed)
4. Example code (reflect new options/parameters)
5. Configuration examples (show new variables/options)
6. Prerequisites (new dependencies or system requirements)
7. Testing instructions (if test setup changed)

Example Patterns

For Model Selection Features (e.g., mapping service):

• List ALL available models/options in overview
• Show build command for EACH variant
• Update API examples to mention model selection
• Update health check/status responses with new model info

For New Services:

1. Create docs/user-guide/microservices/<service>/ directory structure
2. Write <service>.md with feature descriptions and API endpoints
3. Write get-started/build-from-source.md with build instructions
4. Create or update API references (api-reference.md and/or _assets/*.yaml) if applicable
5. Create tests/README.md with test execution instructions
6. Update root docs/user-guide/ with cross-service documentation
7. Update main README.md if major functionality change

For Configuration Changes:

1. Document all new environment variables in the service overview (<service>.md)
2. Provide example .env snippets
3. Update build-from-source.md with configuration instructions
4. List new configuration files or schema changes
5. Show examples of before/after configurations if behavior changed

For API Changes:

1. Update OpenAPI/Swagger spec (_assets/*.yaml) or api-reference.md
2. Update service overview (<service>.md) with new endpoints/parameters
3. Update example code in build-from-source.md
4. Document deprecations or breaking changes
5. Provide migration guides if backward compatibility broken

Service-Specific Documentation Examples

Controller Service

• Overview (docs/user-guide/microservices/controller/controller.md): Scene management, object tracking, REST API
• Build (docs/user-guide/microservices/controller/get-started/build-from-source.md): Makefile targets, Docker commands
• API Spec (docs/user-guide/microservices/controller/api-reference.md and _assets/scene-controller-api.yaml): gRPC/REST endpoint definitions
• Data formats (docs/user-guide/microservices/controller/data_formats.md): Canonical MQTT contracts, including External Source Input Message Format
• External-source adapter how-to (docs/user-guide/how-to-guides/publish-external-source-adapter.md): Procedure for converter scripts (links to data formats; does not duplicate field tables)
• External-source adapter skill (.github/skills/external-source-adapter/SKILL.md): Agent checklist; points at the how-to and data formats
• Tests (controller/tests/README.md): Unit, functional, integration test execution

When changing the external_source / external_pose / external_detection contract: update the schema and data_formats.md first, then verify links and checklists in the how-to and .github/skills/external-source-adapter/SKILL.md still resolve. Do not restate field tables in the how-to or skill.

Manager Service

• Overview (docs/user-guide/using-intel-scenescape/ and related guides): Web UI features, REST API, database schema
• Build (docs/user-guide/how-to-guides/deployment/preparation.md and root build guides): Django setup, migrations, static files
• API Spec (docs/user-guide/api-reference.md): REST endpoint definitions
• Tests (manager/tests/README.md): UI tests, functional tests, API tests

Autocalibration Service

• Overview (docs/user-guide/microservices/auto-calibration/auto-calibration.md): Calibration algorithms, input/output formats
• Build (docs/user-guide/microservices/auto-calibration/get-started/build-from-source.md): Build commands, dependencies
• API Spec (docs/user-guide/microservices/auto-calibration/api-reference.md): REST API for calibration requests

Cross-Service Documentation

Root-level documentation in docs/user-guide/:

• Architecture overview - System design and component interactions
• Getting Started (docs/user-guide/get-started/installation.md) - Prerequisites, getting the source, and choosing a deployment; links out rather than holding commands
• Build Instructions - Root Makefile targets, build system overview
• Deployment (docs/user-guide/how-to-guides/deployment/) - preparation.md (source-build vs prebuilt setup), deploy-docker.md, deploy-kubernetes.md, deploy-demo.md
• Development Guide - Local development workflow
• Testing - Test execution across all services
• API Reference - Complete API documentation index

Update root documentation when:

• Making changes that affect multiple services
• Updating build system or deployment procedures
• Adding new testing procedures
• Changing development workflow