1. All the docs live on one gigantic page, so you scroll forever and lose your place every time the page refreshes. 2. The left-hand “table of contents” is just one flat list—no collapsing or nesting—so you stare at hundreds of endpoints with zero hierarchy. 3. No in-page search or filter; finding “/clockins” means manual eye-scanning. 4. Endpoint links contain stray “]” escape characters that look sloppy and trip screen readers. 5. Parameters and responses are shown as bullet lists instead of proper tables, so you can’t skim name → type → description. 6. Field types contradict themselves (e.g., “array[ScheduleBreakData] (string)”), undermining trust in the spec. 7. Example JSON includes dangling commas (“manual,”) that will break copy-and-paste requests. 8. Times are Unix-epoch only; ISO 8601 is the modern, readable, JSON-friendly standard. 9. No copy-to-clipboard buttons on code or curl snippets—basic dev-experience feature missing. 10. No interactive “Try it” console or sandbox; you have to leave the page for Postman. 11. Code samples aren’t embedded—just a link to GitHub—forcing a context switch. 12. No per-endpoint error model or status-code list, so you have to guess what 400 or 429 looks like. 13. Rate-limit policy is buried in a generic section and never referenced next to individual calls. 14. Authentication quick-start is scattered; there’s no single “get your first token in 30 seconds” flow. 15. Resource names are inconsistent (“departments” vs “teams”), adding mental overhead. 16. No downloadable OpenAPI/Swagger or Postman collection, blocking auto-generated SDKs. 17. Accessibility is weak: no ARIA landmarks, low-contrast bullets, and escaped characters hinder screen readers. 18. Layout isn’t mobile-responsive; the wide nav squeezes content or disappears on phones. 19. No version selector or deprecation banner—future versions will strand users. 20. Critical info (base URL, auth header format, pagination rules) is buried at the same visual level as trivial notes, so newcomers miss what actually matters.
