API Documentation Improvement Plan (v2)

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

• 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.

• 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.

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.

• 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.