# API Documentation Improvement Plan (v2)

**Last Updated:** 2026-01-01
**Status:** In Progress

## Goals

- Keep terminology consistent across descriptions while preserving API contracts (paths, field names, enums).
- Ensure operationIds remain snake_case and aligned with standard entity names.
- Sanitize example data/placeholders to avoid Russian markers.
- Reorder methods within tags for consistent reader experience.


## Current State

- **Terminology:** Descriptions use the standard vocabulary (location, team member, appointment, etc.). Continue spot checks, especially when adding new sections.
- **Operation IDs:** snake_case and terminology-aligned; no pending fixes identified.
- **Example data:** Russian names/icons removed; examples now use neutral/US-style names, phone codes (+1), and non-Russian icons.
- **Method sorting:** Not started. Needs implementation per GitHub-style ordering.


## Next Actions

1. **Guardrails for new content**
  - Keep contract fields intact (e.g., legacy `master_request` keys), but describe them in English and prefer “team member” in text.
  - Avoid `.ru` domains, Russian social networks, Cyrillic, Russian area codes/timezones in examples.
  - Quick checks:
    - `rg '[А-Яа-я]' docs`
    - `rg 'Odnoklassniki|Oksana|Sergei|Sidorov|Olga|Natalia' docs`
2. **Method sorting (planned execution)**
  - Apply GitHub-style order inside each tag: LIST → SEARCH → GET → CREATE → UPDATE → DELETE → SUB-RESOURCES → ACTIONS → DEPRECATED.
  - High-priority tags: Loyalty Cards; Products & Inventory; Sales & Payments; Activities & Events; Subscriptions & Certificates; Loyalty Programs; Schedule & Resources.
  - Exceptions: keep user-journey order for Online Booking; keep auth flow ordering for auth tags; keep logical grouping for Analytics.
3. **Validation after edits**
  - `make lint`
  - `make build-dev`
  - Visual spot-check of reordered tags in the rendered docs.


## Maintenance

- Use US/UK-style names (e.g., Alex Taylor, Sam Carter), phone codes `+1`, and timezones like `America/New_York` in samples.
- Update this document when method sorting is executed or new guardrails are added.