Для docs.microsoft.com внедряется новая система отзывов

Автор этой записи — Роб Айзенберг (Rob Eisenberg), старший руководитель программы в команде docs.microsoft.com.

Миссия корпорации Майкрософт — помочь каждому человеку и каждой организации на планете добиться большего. Это стремление стало одним из тех соображений, которые легли в основу нашей новой системы отзывов docs.microsoft.com на основе открытой платформы GitHub. Мы переходим на следующий уровень и перемещаем систему отзывов в документацию на основе GitHub.

Отзывы о содержимом на GitHub

Хотя наша документация была расположена на GitHub с самого начала, для реализации отправки отзывов о содержимом (комментариев к статьям) мы использовали решение Livefyre. Livefyre — это прекрасное решение для реализации комментариев, однако оно оказалось недостаточным для наших задач — сохранять состояние вопросов, связанных с содержимым, от наших клиентов, отслеживать эти вопросы и назначать владельцев для них.

Мы изучили несколько вариантов улучшения этой системы, но основной вопрос, которым мы руководствовались в своей работе, звучал так: Если рассматривать нашу документацию как открытый исходный код, то как бы мы решили эту проблему? Ответ на этот вопрос казался очевидным: вопросы GitHub. Поэтому мы начали экспериментировать с более глубокой интеграцией API GitHub в нашу документацию и смогли разработать полноценную систему отзывов на основе инфраструктуры GitHub.

С новой системой вы можете создавать вопросы GitHub прямо на странице содержимого, что позволяет вам гораздо активнее взаимодействовать с авторами статей и командами по разработке продуктов. Увидели ошибку в документе? Неправильный пример кода? Невразумительное объяснение? Важное упущение? Просто перейдите в нижнюю часть страницы и выберите Отправить отзыв о документации.

Вход пользователя в систему и добавление отзыва

Все открытые и закрытые вопросы, связанные с документом, отображаются на самой странице документации — так вы всегда сможете узнать о том, какие вопросы решены и закрыты:

Демонстрация открытых и закрытых вопросов

Вы можете добавлять комментарии и даже реакции к тем вопросам, которые важны для вас:

Добавление реакций к вопросам GitHub

Теперь сотрудники корпорации Майкрософт могут использовать все возможности вопросов GitHub, чтобы рассматривать, планировать, решать вопросы и оставлять ответы на них — и вы всегда сможете это увидеть!

Пример отзыва о документации

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

Кроме того, вы можете использовать все стандартные возможности GitHub: разметка Markdown в комментариях, подписки на отдельные вопросы или целые репозитории, RSS-каналы деятельности организации, @упоминания, исполнители и многое другое! Мы считаем, что более тесная интеграция с открытым инструментом позволит реализовать новые возможности по развитию сообщества и совместной работе.

Разделение отзывов о продукте

Одним из недостатков предыдущей системы было смешивание отзывов о продуктах и документации в одном потоке. Это сильно затрудняло рассмотрение и решение вопросов, а должным образом помечались не все элементы. Мы сделали шаг вперед в решении этой проблемы, разделив отзывы о продуктах и документации:

Отправка отзывов о продукте

Теперь щелкнув ссылку Оставить отзыв о продукте, вы перейдете прямо на сайт, на котором команда продукта, связанная с конкретной страницей документации, обрабатывает отзывы о продукте.

Развертывание

Вы можете спросить, когда будет развернута новая система отзывов. Мы тестировали новую систему отзывов несколько месяцев для интегрированной среды разработки Visual Studio и документации по Azure CLI. Начиная с середины февраля мы будем развертывать эту систему для всего сайта docs.microsoft.com.

Ваш отзыв

Ваши отзывы очень важны для нас, поэтому мы хотим предоставить эту систему в ваше распоряжение как можно быстрее. Это наш следующий шаг для улучшения системы отзывов и повышения вовлеченности пользователей на нашей платформе, но это отнюдь не последний шаг. Поделитесь своим мнением об этих изменениях на сайте UserVoice или отправьте запись с соответствующим хэштегом в Twitter.