Знакомство с 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). В будущем по мере развития платформы на основе ваших отзывов мы перенесем на нее больше документации.

Основные функции

Давайте начнем с примера страницы документации (показан ниже); в его рамках мы продемонстрируем некоторые новые возможности сайта.

Documentation Example

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

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

Docs and TechNet comparison

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

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

Estimated reading time

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

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

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

Intune documentation screenshot

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

Left navigation

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

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

Back and Next buttons

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

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

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

Responsive Page Design

Материалы сообщества

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

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

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

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

Comments link

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

Comments at bottom

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

Sidenote example

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

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

Sharing to Twitter and Facebook

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

Select and comment or share content

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

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

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

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

Light and Dark Theme Selector

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

Light and Dark themes

Основы

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

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

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