а еще, вы как пишете документ, один, и пользуетесь им 10 лет?)

обычно документы актуализируются, ну это в моем мире

Что и как взаимодействует — это guides. Описание методов, что умеет делать API — это reference.

Благодарю!

Жаль. Разработчик так думает из экономии энергии. Просто ему очевидны те вещи, которые не очевидны тому, кто впервые видит библиотеку.

У нас вот неглупые клиенты, но удаляли удалённый указатель и делали прочие смешные вещи, например вызывали метод без инициализации библиотеки. Всякое бывает.

Типичная проблема курицы и яйца. У разработчика своя правда. Чем меньше деталей, тем меньше наведённых ошибок. Что должно быть описано раньше. Написал про Get и Set, получил сложности с вопросами о том, как они работают. А написал "свойство", и вроде бы и проблем нет. Но они есть у пользователя.

проблема в том, что в меня кинули этими методами, и попросили написать техническое описание, как работает сервис. потому что РАЗРАБОТЧИКИ НЕ ЗНАЮТ

На тему того, какие нужны типы документов, мне понравился этот доклад: https://www.youtube.com/watch?v=t4vKPhjcMZg&feature=emb_logo

По поводу "бумажных" документов.

Нас иногда просят сделать документ в Word, который описывает, как использовать API в какой-то ситуации, для решения каких-то определенных задач.

Что обычно содержит документ:
— введение в контекст: описание, о какой бизнес-задаче пойдёт речь, о возможностях API для решения этой задачи, о каких-то специальных условиях (например, нужны какие-то определенные настройки)
— описание сценария взаимодействия: по каждой подзадаче диаграмма последовательности и/или словесный сценарий, как будет проходить процесс, кто участники процесса, кто что в какой последовательности делает
— описание формата взаимодействия, например, по какому адресу отправлять запрос, в каком формате передавать данные, что придёт в ответ
— инструкции, как решить какую-то задачу, с примерами запросов и ответов (успешных, неуспешных)
— описание конкретных методов и их параметров, каких-то справочных данных (например, описание ошибок)

В зависимости от ситуации эти данные могут объединяться, исключаться, что-то может добавляться и т.д. Например, последние два пункта иногда совмещены, потому что мы описываем, как решить определенную задачу (т.е. это больше инструкция с описанием каких-то дополнительных параметров).
При необходимости, отсылаем в полный справочник методов (он у нас публичный).

Если ваш API обновляется, то надо будет продумать, как сопровождать бумажный документ, чтобы он всегда был актуальным.

Это реально бывает, да. На этот случай есть архитектор.

это в каком-то идеальном мире.

Никогда не понимал и сейчас не понимаю смысл справочника API. О смысле полей можно догадаться. А вот работа с их методами, примеры работы, важная информация для начала работы.

Докладывает разработчик, вы не правы. Документация к API отвечает на вопросы "что произойдет, если я вызову этот метод", а не на вопрос "когда я должен использовать этот метод". Спрашивайте ваши ответы :)

вы разработчик?

Это справочник на это отвечает.

Так точно. Даже что-то программировал.

Документация к API является справочником, а не учебником

И на вопрос "почему вам нужен именно справочник" ответ очень прост - если в вашей справке написано, как решать некоторую задачу, почему она еще не решена?

Не согласен. Посмотрите https://python.readthedocs.io/en/latest/

Там часто очень детально написано, как работать с API.

Некорректно. Бывают вспомогательные теоремы.

Стас прав