Знакомство с docs.microsoft.com

Публикацию подготовил Джефф Сэндквист (Jeff Sandquist), директор подразделения Cloud and Enterprise.

Сегодня мы анонсируем предварительный выпуск новой службы документации https://docs.microsoft.com и демонстрируем контент, поддерживающий продукты Enterprise Mobility.

Почему docs.microsoft.com?

Если кратко, то контент — это важно. Мы провели интервью и опросы с сотнями разработчиков и ИТ-специалистов и просмотрели отзывы в UserVoice за последние годы. Было ясно, что нужны перемены: необходимо было создать современный веб-сайт для контента. Первое, что мы сделали, — оценили существующую инфраструктуру контента TechNet и MSDN. Оба сайта созданы на основе нестабильной базы кода 10–15-летней давности с устаревшей системой публикации и развертывания, не предназначенной для работы в облаке.

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

Стало понятно, что для создания нужного интерфейса необходимо начать с чистого листа. Так мы создали https://docs.microsoft.com — новую базу документации Майкрософт.

Примечание. Эта предварительная версия веб-сайта включает контент *только* для документации по Enterprise Mobility (которая состоит из служб Advanced Threat Analytics, Azure Active Directory, Azure Remote App, Многофакторная проверка подлинности, Azure Rights Management, Intune и Microsoft Identity Manager). В будущем по мере развития платформы на основе ваших отзывов мы перенесем на нее больше документации.

Основные возможности

Начнем с примера страницы документации, показанного ниже, и продемонстрируем некоторые новые возможности сайта.

Удобочитаемость

Чтобы повысить удобство чтения, мы задали ширину контента на сайте. Исследования по окулографии показали, что можно улучшить понимание и скорость чтения, задав ширину текста контента, так как глазам сложно следить за длинными абзацами. Чтобы увидеть это в действии, ознакомьтесь с примером статьи Intune ниже на сайте docs.microsoft.com и с той же статьей на сайте TechNet. Кроме того, по просьбам клиентов мы увеличили размер шрифта для левой панели навигации и самого текста (UserVoice — увеличение размера шрифта).

Предполагаемое время чтения

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

Навигация по контенту и сайту

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

Ниже приведен снимок экрана домашней страницы Документация Intune:

Те же категории находятся на левой панели навигации статей:

Сокращенные статьи

Нередки были отзывы о том, что иногда материалы неудобны для восприятия из-за объема: в них сложно ориентироваться и находить нужное. Для решения этой проблемы мы разбили многие длинные статьи на меньшие по размеру логические фрагменты и добавили кнопки "Назад" и "Далее" внизу статей, чтобы перемещаться по ним, как по учебнику из многих частей, как показано ниже.

Многим клиентам такие учебники понравились; при этом мы также учли и мнение тех, кто хотел бы иметь возможность совместить такие учебники в единый PDF-документ, который легко распечатать. Последней возможности пока нет, но скоро в рамках предварительной версии она появится.

Гибкий дизайн

Для оптимизации интерфейса на мобильных устройствах, планшетах и ПК в соответствии с UserVoice мы перешли на динамический макет. Нажмите кнопку "Параметры", чтобы развернуть или свернуть те же параметры в представлении рабочего стола.

Вклады членов сообщества

Вся документация на сайте docs.microsoft.com содержит открытый исходный код, чтобы сообщество могло внести свой вклад. Это сделано по примеру других групп в Майкрософт, которые уже открыли исходный код для всей документации или ее части, в том числе ASP.NET, Azure, .NET Core и Microsoft Graph.

В каждой статье есть кнопка "Изменить" (показана ниже), по которой осуществляется переход к исходному файлу Markdown в GitHub, где можно легко отправить запрос на включение внесенных изменений для исправления или улучшения контента.

Механизмы обратной связи

Ваши вопросы, комментарии и отзывы важны для нас. Мы сотрудничаем с [Livefyre](https://web.livefyre.com/) для предоставления комментариев и сносок для всех наших статей. В начале каждой статьи находится ссылка на комментарии, как показано ниже.

Щелкните "Комментарии", чтобы перейти к нижней части страницы, где можно войти в систему (с помощью учетных данных Twitter, Facebook, Google, Yahoo или Майкрософт), чтобы добавить комментарии, подписаться на них или поставить отметку "Мне нравится".

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

Публикация в социальных сетях

Кнопка публикации в верхней части страницы позволяет легко поделиться материалами в Twitter и Facebook.

Кроме того, можно выбрать мышью контент в статье, чтобы напрямую добавить комментарий или поделиться статьей в Twitter или Facebook из контекстного меню, показанного ниже.

Понятные URL-адреса

Нам важно, чтобы работа с сайтом была удобной, и нас как пользователей TechNet и MSDN постоянно беспокоило отсутствие в статьях понятных URL-адресов. Вот пример статьи с новыми URL-адресами.

• Перед:<https://technet.microsoft.com/library/dn646983.aspx>

• После:<https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune>

Тема веб-сайта

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

На следующем рисунке показано различие между светлой и темной темами.

Базовый

Такие основы, как производительность сайта, особо важны. Именно их многие клиенты просили нас улучшить в UserVoice. Время загрузки страницы на сайте docs.microsoft.com стало на 50–300 % меньше, и мы оптимизировали географическое распределение. Сайт разработан на архитектуре, которая полностью выполняется в Azure.

Ждем ваших отзывов!

Надеемся, вам понравилась предварительная версия docs.microsoft.com. Отправляйте отзывы на адрес https://aka.ms/sitefeedback. В следующих публикациях будут рассматриваться планы по существенному улучшению интерфейса для справочных материалов, а также планы по локализации контента.