Тема: Документирование методов и процессов API
Наблюдаю из года в год как девушки на форуме консультируют многих разработчиков по куче вопросов, многие из которых повторяются. И натолкнуло это меня на воспоминание сцены в одном юридическом институте... Прошло минут 20 лекции и тут заходят опоздавшие. Лектор, практикующий юрист, говорит: - Знаете, почему я никогда не ругаю опоздавших? Потому что благодаря таким, как вы, у меня есть работа.
Почему, казалось бы, у девушек тут есть целый вал работы по консультации? Благодаря аналитику, похоже. Он не может внятно всё изложить. Так, чтобы было понятно впервые увидевшим ваши API. Многие описания методов выглядят однострочно. Пара фраз, куцый пример одного или двух кейсов, всё... Дальше сами сидите и разбирайтесь.
Сколько уже я часов потратил на то, чтобы ваши методы, так лаконично описанные, наконец-то заработали. Молчу уже об отсутствии описания процессов. Зачем нужны события? Чем получать историю простоев за период? Какие методы существуют для работы с данными по списку ТС, а не по одному объекту?
На моём опыте есть интеграции и гос.учреждениями, яндексом, гуглом, трелло, ютреком, сервисами доставки вроде сдэк или рэдэкспресс, объединениями вроде РСА... Я уже как-то говорил, у вас худшая документация из всех, что я видел.
Раз тут неформальное общение, вы можете приоткрыть завесу тайны, зачем вы набираете консультантов для консультаций на форуме, зачем вам выгодно терять в рейтинге (если мне как программисту не нравится виалон, новому работодателю я посоветую Ом****м, например), когда всё это решается лишь приданием стимула аналитику?
Посмотрим для примера https://sdk.wialon.com/wiki/ru/sidebar/ … /load_last
Чтобы загрузить последние несколько сообщений на указанный момент, нужно использовать команду
А зачем мне сообщения грузить на сервер? Или я загружаю себе с сервера? Откуда я беру эти сообщения? И как они там появляются?
Что из указанных операндов является обязательным, а что нет?
Какие могут быть получены коды ошибок на данный метод и что они означают кроме краткой аббревиатуры?
Есть случаи несоответствия типов операндов описанным в документации. Также есть случаи несоответствия форматов ответов.
На странице нет примера запроса, нет примера полного ответа. Нет ссылок, что надо делать до этого метода, чтобы его выполнение было корректно. Нет ссылки на то, что делать потом, после этого запроса, если он не является конечным.
В случае отчётов это вообще труба. Я рад, что мне достался код предыдущего программиста и я не с нуля постигал логику, что сначала ищем шаблон, затем его очищаем, затем строим запрос, затем получаем список таблиц, затем получаем строки таблиц... Не могу сказать, что этот процесс прост и логичен, но раз уж он такой, можно было бы дать где-нибудь сквозной и самодостаточный пример последовательности запросов и примеры ответов?
Кроме того, ради сокращения объёма данных, вы сократили все имена в пакетах ответов. Программисту было бы понятно, что c.dt[3].f.v - это время события (пример абстрактный), если бы вы дали таблицу с нормальным описанием формата ответа: условное сокращение - что оно означает вообще - тип - описание. Например, с - columns или c - configuration.
Во времена, когда давно изобрели сваггер, иметь такую документацию - это немного позор, не находите?
Очень хочется услышать вашу оценку вашей документации апи. И если есть понимание, то сроки бы, когда вы её сделаете полной и удобной?
)