1

Документирование методов и процессов API

Тема: Документирование методов и процессов API

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

Чтобы загрузить последние несколько сообщений на указанный момент, нужно использовать команду

А зачем мне сообщения грузить на сервер? Или я загружаю себе с сервера? Откуда я беру эти сообщения? И как они там появляются?
Что из указанных операндов является обязательным, а что нет?
Какие могут быть получены коды ошибок на данный метод и что они означают кроме краткой аббревиатуры?
Есть случаи несоответствия типов операндов описанным в документации. Также есть случаи несоответствия форматов ответов.
На странице нет примера запроса, нет примера полного ответа. Нет ссылок, что надо делать до этого метода, чтобы его выполнение было корректно. Нет ссылки на то, что делать потом, после этого запроса, если он не является конечным.
В случае отчётов это вообще труба. Я рад, что мне достался код предыдущего программиста и я не с нуля постигал логику, что сначала ищем шаблон, затем его очищаем, затем строим запрос, затем получаем список таблиц, затем получаем строки таблиц... Не могу сказать, что этот процесс прост и логичен, но раз уж он такой, можно было бы дать где-нибудь сквозной и самодостаточный пример последовательности запросов и примеры ответов?
Кроме того, ради сокращения объёма данных, вы сократили все имена в пакетах ответов. Программисту было бы понятно, что c.dt[3].f.v - это время события (пример абстрактный), если бы вы дали таблицу с нормальным описанием формата ответа: условное сокращение - что оно означает вообще - тип - описание. Например, с - columns или c - configuration.
Во времена, когда давно изобрели сваггер, иметь такую документацию - это немного позор, не находите?
Очень хочется услышать вашу оценку вашей документации апи. И если есть понимание, то сроки бы, когда вы её сделаете полной и удобной?

2

Документирование методов и процессов API

Re: Документирование методов и процессов API

Прошу прощения, не в том разделе опубликовал. Перенесите, плз, в https://forum.gurtam.com/viewforum.php?id=23

3

Документирование методов и процессов API

Re: Документирование методов и процессов API

Добрый день!

Спасибо за ваш фидбек, за честное мнение.

Действительно по многим пунктам с вами соглашусь - документация стара, не хватает примеров, не всегда есть точные описания. Хотя мы постоянно ее корректируем, исправляем не верную информацию в том числе , что сами нашли, и что нашли (помогли) наши пользователи.

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

Вторая проблема - это старый движок, который не позволяет делать какие-то крутые удобные штуки.

К сожалению, по этим причинам (в том числе) мы не можем просто нанимать девушек-консультантов, т.к ответы на вопросы API требует хорошее знание Wialon, опыт работы с системой, знание программирования, практическое использование Wialon API в повседневных задачах.

Но пользователи, особенные новые, не обязаны знать и понимать сразу все , поэтому консультации на форуме есть и будут, более того мы запустим серию вебинаров по SDK , как раз рассчитанную на новых пользователей, пользователей, кто сталкивается с абсолютно не понятными типами запросов, есть какие-то камни преткновения, и т.д.   - первый выпуск скоро выйдет
https://www.youtube.com/watch?v=NxXDN7F … e=youtu.be
(воспользуюсь моментом и анонсирую свой вебинар smile )
Если у вас также есть идеи/вопросы/темы, которые хотелось бы услышать на вебинарах, пожалуйста, пишите - на мою почту chdi@gurtam.com
Также , раз уж речь зашла про видео , еще есть достаточно хорошие , сделанные давно, но еще актуальные , видео-уроки, описывают основные методы, работы с ними (там только про метод логина уже не актуально), оставляю ссылку на всякий случай - ( на английском языке содержание только)  - https://www.youtube.com/playlist?list=P … jwq8AfgmAh

Это про текущую ситуацию (приоткрываю завесы smile )

Теперь про будущее планы.

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

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

Diana Cheley
Wialon Hosting Expert
Gurtam
4

Документирование методов и процессов API

Re: Документирование методов и процессов API

Отличные новости! Обязательно подключусь к вебинарам.