Review the API documentation for a developer-tools company of JetBrains's kind - 140 pages of hand-written endpoint reference, a "getting started" guide written at launch three years ago, a changelog that stops 18 months back, and a support inbox where the same six questions recur. What would you delete, what would you generate, and what would you add?

What is actually required

Documentation exists to answer the questions integrators are asking. The support inbox is a measurement of exactly that, and the same six recurring questions are the entire specification for this work. Everything else in the review is secondary to them.

What I would delete

• The hand-written endpoint reference. 140 pages maintained by hand against a changing API is guaranteed to be wrong somewhere, and wrong reference documentation is worse than none: a developer who finds a documented field that does not exist cannot tell which half of your documentation to trust. Replace it with a generated reference, and delete the prose version rather than keeping both.
• The three-year-old getting-started guide, if it no longer runs. A tutorial that fails at step four is the single worst artefact in a developer portal, because it is the first thing a new integrator touches and it teaches them that nothing here is maintained.

What I would generate

• The endpoint reference, from the specification - and derive the specification from the implementation or verify the implementation against it in CI. Either direction works; what does not work is a specification maintained as a separate document by hand.
• The changelog, from the release process. A changelog that stops 18 months ago tells integrators that either nothing changed - which they know is false - or that nobody is writing it down. Generating it from release metadata makes it a by-product rather than a chore.

What I would add

• One answer per recurring support question, written as a task ("how do I handle a webhook retry?") rather than as reference. Six pages, each shortening a support thread, is the highest return available here.
• Runnable examples that are tested. Every example in the documentation should execute in CI against a real environment, so it cannot rot. This is the single mechanism that keeps documentation honest, and it converts documentation from a writing task into a testing one.
• An errors page listing every error code with its cause and the correct client response. Integrators need it and reference documentation generated from a schema rarely contains it.

What I would leave alone even though it looks odd

The 140-page structure, if integrators navigate it successfully. Restructuring a portal is visible work that mostly satisfies the team's own taste. Check the analytics first: if people are finding things, leave the information architecture and fix the correctness.

How I would argue this in the review

With the support inbox. "These six questions cost us 40 support threads a quarter" is a measurable claim that connects documentation work to a cost someone already feels. An argument for better documentation on quality grounds alone loses to a feature every time, and the recurring question count is the number that wins it.

When this is the wrong priority

If the API itself is unclear - inconsistent naming, surprising error semantics, an authentication flow nobody gets right first time - documentation is being used to paper over a design problem, and the recurring questions are telling you about the API rather than about the pages. Fix the two worst inconsistencies first; some of the six questions will disappear without a single page being written.