Open kazeevn opened 9 years ago
МФТИ пишет, что они сделали отдачу уникального id, общежития, комнаты и группы. Лёша, когда у тебя будет возможность проверить?
На выходных. Я посмотрел инструкцию к их ouath на сайте, там пока ничего про комнаты и группы нет. И кажется, что там вообще ничего дельного нет.
Я списался с Нуждиным, он сказал, что только сделали.
Никого не хочу обидеть, но этим ребятам стоит завести специально обученного человека для написания документации. С первого взгляда походит на хаос с кусочками кода на php :(
;) Это ещё далеко не худшее, что бывает. Но ты, конечно, права, что раз они позиционируют API как публичное, то документацию стоит улучшить. Если ты конструктивно сформулируешь недостатки, их вполне можно указать - коллеги из МФТИ показались мне адекватными.
И правда не худшее, но это слабое оправдание, надо сказать. Не готова заниматься полной классификацией ошибок (по крайней мере, сейчас), но примеры можно найти быстро. Вот четыре последовательных (почти случайно выбранных) строчки:
Ждем пользователя с ответом от сервера. Куда-то приходит пользователь. Да ещё и с ответом от сервера. Приложения у нас, видимо, общаются гонцами.
_Получаем пользователя, добро, code и state на redirecturi. Ладно, с пользователем разобрались. Но помимо code и state мы получаем какое-то добро. Ну, добра вам, люди! Но это, видимо, код ответа 200 (это предположение).
Далее по листингу файла receivecode.php из основной статьи. Что по листингу файла?
Распишем функционал команд клиентской библиотеки, куда они обращаются и что они получают Всё казалось бы хорошо, но кто такая клиентская библиотека, чёрт подери? Методом дедукции искомое было найдено (но правда же неочевидно, что это именно она называется "clienttoauth.zip"!)
Ну и да, все исходники скромно прячутся где-то в середине странице под ссылками типа "здесь" или "выше". Чтобы скачать код, нужно за ним поохотиться.
За некоторое время мы, конечно, смогли применить телепатию, почитать readthedocs и сделать выводы, но там ведь две страницы такого текста!
Доброго времени суток. Впрочем, я просто скопирую из диалогов ВКонтакте свой ответ.
Доброй ночи) Благодарю за оказанное внимание к документации, но по порядку: 1) "Ждем пользователя с ответом от сервера. Куда-то приходит пользователь. Да ещё и с ответом от сервера. Приложения у нас, видимо, общаются гонцами." Как бы глупо не звучало, но так оно и есть. По стандарту OAuth 2.0 сервер делает редирект пользователя с ответом сервису в гет-запросе 2) "Получаем пользователя, добро, code и state на redirect_uri. Ладно, с пользователем разобрались. Но помимо code и state мы получаем какое-то добро. Ну, добра вам, люди! Но это, видимо, код ответа 200 (это предположение)." Добро - это разрешение пользователя на передачу данных, иначе отдается ошибка Прошу прежде чем делать такие выводы, ознакомиться с официальными стандартами OAuth 2.0 А более простые слова поданы для упрощения восприятия простым "самоучкой" Т.к. данный сервер также ориентирован на данный момент также на Битрикс.Маркетплейс, где на самом деле бОльшая часть людей - малознающие люди 3) "Далее по листингу файла receivecode.php из основной статьи. Что по листингу файла?" Это уже придирка Все ссылки указаны на конкретные строки и якори 4) "Распишем функционал команд клиентской библиотеки, куда они обращаются и что они получают Всё казалось бы хорошо, но кто такая клиентская библиотека, чёрт подери? Методом дедукции искомое было найдено (но правда же неочевидно, что это именно она называется "clienttoauth.zip"!)" Ссылка на клиентскую библиотеку НАПРЯМУЮ указана в содержании
Но благодарю за оказанное внимание и критику к документации
Я понимаю, что это взгляд девушки. Но ради понятия восприятия "простыми" сторонними людьми я сразу после написания документации предложил своей супруге (к слову, ни капли не технарь) прочесть её. Что интересно, она поняла как что работает и даже поняла что за что отвечает.
И кстати, большАя часть базы документации - перевод и "разжевывание" документации Брента Шаффера (разработчик/программист Adobe) Полагаю, если данной особе дать его документацию, то она совсем расстроится)) Т.к. понять целиком спецификацию OAuth очень трудно, поэтому я действовал по тому же принципу, что и Б. Шаффер, сделать более дружелюбную документацию
Конечно же, документация требует улучшений, я только за) каждый пытается понять и сделать так, как он привык, поэтому скорее я попытаюсь более структурировать её, сохранив дружелюбный "рассказ"
По данной документации работаете не Вы первые и не Вы последние, но никто до сих пор в "таком" характере не жаловался. Пока только благодарили за разжеванность и поддержку.
Здравствуйте, уважаемый gr1ff0n. Ещё раз искренне извиняюсь и повторяю, что обидеть никого не хотела. Мой тон часто бывает категоричен, к сожалению. Да, я действительно совершенно не разбиралась в механизмах работы OAuth (особенно на момент прочтения инструкции). А инструкция всё-таки написана для тех, кто хорошо понимает, что происходит. Предвижу фэйспалмы с вашей стороны, но поверьте, я тоже писала гайды для полных новичков в области. Не в области OAuth, конечно, но всё же. Состояние аффекта, в котором я всё это писала, было вызвано неожиданностью. Так уж сложилось, что подключение OAuth популярных сервисов (например, того же gmail, подключение к которому у нас уже есть) специальных знаний как раз не требовало.
А как, кстати, пол "данной особы" (то есть, меня) влияет на профессиональные качества (естественно, вы теперь не слишком высокого о них мнения)? И как это объясняет то, что мой коллега испытал трудности, схожие с моими?
Тем не менее, большое спасибо за пояснения по существу.
Про профессиональные качества никто не говорил, мне пока их наблюдать не удалось, но я уверен в их наличии. Проблема в том, что так сложилось, что большая часть девушек относится предвзято, категорично и в спешке делает выводы без поиска причины, лишь потому, что они так не привыкли.
Не стоит продолжать обсуждать личностные качества, это не несёт конструктивного элемента.
Если говорить конкретно, то эта документация больше походит на туториал по oauth2 и использованию вашей библиотеки. Лично мне нужны были примеры запросов для работы с API и адреса точки авторизации и токена. Примерно то, что есть на странице http://mipt.ru/api/help/oauth/ в разделе про функционал библиотеки.
Было бы проще, если бы на той же странице был отделён порядок получения client key/secret от самого процесса общения с сервером и примеры работы не были бы связаны с функционалом библиотеки (чтобы не приходилось переходить на предыдущую страницу и пытаться разобраться в коде).
Про ссылку на библиотеку.
Совершенно неочевидно, что строка в оглавлении является ссылкой на скачивание кода. Обычно ссылки в оглавлении ведут на определённые места в странице и созданы для удобства навигации.
alexsyrom Благодарю за конструктивную критику. В ближайшее время файлы выделю в отдельный раздел и реорганизую чисто техническую информацию (функционал и точки).
Для желающих постигнуть дзен - Янедкс недавно делал целую конференцию для технических писателей, доступны записи https://events.yandex.ru/events/hyperbaton/18-april-2015/
https://mipt.ru/api/help/oauth/ Поговорил с Нуждиным, они сделают отдачу уникального id, общежития, комнаты и группы - отпадёт необходимость использовать базу rfid, не будет проблем с тёзками.