# Documentation maintenance policy

## Ownership

- **Content owner:** [Elena David](https://reputation-management-service.com/a-propos/elena-david.html)
- **Role:** SEO, ORM, and AI Visibility Consultant
- **Documented application:** Reputation Monitor 1.0.0
- **Current documentation version:** 1.0.4

## Review triggers

Review the collection when:

- application source or `pyproject.toml` changes;
- a CLI option, default, message, exit condition, or output field changes;
- sample data or expected counts change;
- tests are added, removed, or revised;
- the supported Python or pytest range changes;
- a known limitation is fixed or deprecated;
- proposed website routes, templates, or metadata requirements change.

Also perform a scheduled technical review even when no change is reported. Record the actual review date; do not advance dates without checking code, commands, and output.

## Code-to-documentation review workflow

1. Read `pyproject.toml` and all modules under `src/reputation_monitor/`.
2. Compare CLI documentation with `build_parser()` and `run()`.
3. Compare schema documentation with `REQUIRED_FIELDS`, `_parse_review()`, and `ALERT_FIELDS`.
4. Compare matching and alert pages with `analyze_reviews()`.
5. Generate reports from the maintained sample data.
6. Compare documented counts, warnings, fields, and filenames with actual output.
7. Run the complete pytest suite on a supported Python version.
8. Validate internal Markdown links and unique proposed URLs.
9. Update the technical review date only on checked pages.
10. Record the documentation version and change summary.

## Updating executable examples

Run every changed shell command from a clean virtual environment when practical. Preserve exact command syntax and meaningful output spacing. Remove volatile elapsed-time values from expected output unless the time itself is relevant.

Use only synthetic practices and review content. Never paste operational medical, patient, or account information into examples, tests, screenshots, or issue reports.

## Dependency review

Check:

- `requires-python`;
- `[build-system].requires`;
- runtime `dependencies`;
- `[project.optional-dependencies]`;
- pytest configuration.

Do not describe a transitive tool as an application dependency. If dependencies change, update requirements, installation, testing, and QA pages together.

## Versioning and changelog

Use semantic documentation versions:

- **Patch:** corrections that do not alter information architecture;
- **Minor:** new pages, procedures, or meaningful coverage;
- **Major:** incompatible metadata, route, or architecture changes.

Maintain a change entry with date, documentation version, application version reviewed, changed pages, verification commands, and unresolved issues.

### Change log

| Date | Documentation version | Application version | Change | Verification |
|---|---|---|---|---|
| 2026-10-17 | 1.0.0 | 1.0.0 | Updated the existing 18-page collection for Streamlit, optional CSV comparison, supported website import, current metrics, downloads, network safeguards, and local data protection. | 38 pytest cases on Python 3.11; Streamlit startup; metadata, internal-link, sitemap, and static-site validation. |
| 2026-10-17 | 1.0.1 | 1.0.0 | Expanded website import documentation for JSON-LD, Microdata, configured CSS selectors, format detection, record preview, and distinct access/format/no-review outcomes. | 47 pytest cases on Python 3.11; documentation generator and static-site validation. |
| 2026-10-17 | 1.0.2 | 1.0.0 | Documented non-technical restricted-access messaging, the immediate CSV recovery action, preserved session settings, and the distinction from unsupported formats. | 50 pytest cases on Python 3.11; documentation generator and static-site validation. |
| 2026-10-17 | 1.0.3 | 1.0.0 | Replaced the dashboard's technical slider wording with a dynamic maximum-alert-rating label and aligned threshold guidance across existing pages. | 57 pytest cases on Python 3.11, including Streamlit widget interaction; documentation generator and static-site validation. |
| 2026-10-17 | 1.0.4 | 1.0.0 | Replaced technical dashboard CSV confirmations with imported and rejected review counts, retained record-level diagnostics in logs, and aligned the existing operating documentation. | 62 pytest cases on Python 3.11; documentation generator and static-site validation. |

## Deprecation handling

When functionality is deprecated:

1. Mark the affected procedure and replacement accurately.
2. Retain old instructions only for application versions that still require them.
3. Avoid presenting a planned replacement as implemented.
4. Add redirects when a published route changes.
5. Remove obsolete limitations after verifying the corrected behavior and tests.