Developer documentation

Developer documentation is the documentation of your API, SDK or product for those who will integrate with it: external partners, client developers or your own teams. We make not a bare list of endpoints but a working set: a quick start (how to make the first request in five minutes), a reference of methods and fields, code examples, authorization, error descriptions and typical scenarios. We structure it around the real developer’s path, connect it where possible to a source of truth (for example, to an OpenAPI specification, see the “OpenAPI specs maintenance” service) so the reference does not drift from the code, and publish it on a convenient publishing platform. The point is for integration to run on its own rather than turning into correspondence with your support about every field. Importantly and honestly: documentation helps only if it is accurate and maintained. Outdated documentation is worse than none: a developer trusts a wrong description, loses time and loses trust in you (for example, following old docs they call an already-removed method — the integration fails, and that hurts trust more than if the docs had not existed at all); so we generate the reference part from the specification where possible, so it does not lag behind the code, and we build in an update process. Also honestly: if your API has one or two internal consumers and is simple, a full documentation portal may be excessive — sometimes a good README is enough, and we will say so. Full documentation is justified when the API is exposed externally, there are many consumers or they are not under your control and cannot just “ask in the next chat”. And about the scope without illusions: good documentation is work, not an export of code comments; writing clearly for a human and thinking through examples and scenarios has to be done deliberately. Picture this: a new partner opens the docs, makes their first successful request in five minutes and then integrates on their own without writing you a single email. The base price starts from 65,000 ₽: a guide for documentation of a compact API; more endpoints, several example languages, complex scenarios and regular updates cost more. Support and updates after handover are agreed separately: we can maintain it or hand it to your team. It depends on the size of the API, the number of scenarios and the platform.

• Developers cannot figure out your API without help — everything goes through support.
• There is no documentation or it is outdated — it is not trusted and people keep asking.
• Partner integration drags on — everyone trips over the same thing.
• Knowledge about the API is in people’s heads — a person leaves and the understanding leaves too.

• A quick start: the first successful request in a few minutes
• A reference of methods, parameters and fields (from the specification where possible)
• Code examples and typical integration scenarios
• Authorization, limits, versioning, error descriptions
• A structure around the real developer’s path, not a bare list of endpoints
• Publishing on a convenient platform with search
• A link to the source of truth (OpenAPI) so it does not drift from the code
• Update rules so the documentation does not go stale

• Developers integrate on their own — less load on support
• Partners onboard faster — the path to the first request is shorter
• The documentation is trusted — it matches the real behavior of the API
• Knowledge about the API is recorded, not living in people’s heads

• We work through the API, the audience and typical integration scenarios
• We write the quick start, reference, examples; link them to the specification
• We publish, set up updating, and hand over to the team

• How is documentation different from an OpenAPI specification and a playground?

  A specification (see the “OpenAPI specs maintenance” service) is a machine-readable description of the API, the source of truth; the reference part is convenient to generate from it. A playground (see the “API playgrounds” service) is an interactive sandbox where a request can be tried right in the browser. Documentation is the explaining layer for a human: a quick start, guides, examples, scenarios. They work best together: the specification as the source, the documentation as the explanation, the playground as “try it”.

• Can’t we just generate the docs from the code and not pay for texts?

  Generating a method reference from the specification — that can and should be done, and we do it. But auto-generation is a dry list of fields; it does not explain where to start, how to authorize, which scenarios are typical and what to do on an error. That human part cannot be obtained automatically — it is exactly what turns a “list of endpoints” into documentation people actually integrate with.

• Will the documentation go stale quickly?

  It will, if it is not linked to the code and not updated. So we generate the reference part from the OpenAPI specification where possible (it is closer to the code), and for guides and examples we build in a review when the API changes. There is no fully “eternal” documentation, but the drift from the code can be kept to a minimum — and that is more honest than promising it is always up to date by itself.