Ноябрьское обновление docs.microsoft.com

Мақала
09/15/2023

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

Сегодня мы рады сообщить об окончании переноса документации по Azure, версии-кандидату Visual Studio 2017, C++, ASP.NET Core, Entity Framework Core и SQL в Linux на сайт docs.microsoft.com.

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

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

В ближайшие месяцы мы добавим документацию по Dynamics 365, Windows Server, SQL Server, System Center и настольным ОС Windows.

В этой публикации

Ключевые возможности сайта документации
Новые возможности сайта документации
Документация по Azure
Документация по версии-кандидату Visual Studio 2017
Документация по C++
Документация по ASP.NET Core
Документация по Entity Framework Core
Документация по SQL в Linux

Ключевые возможности сайта документации

Для тех, кто не знаком с сайтом docs.microsoft.com, представляем ряд ключевых возможностей, доступных на нем.

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

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

Мы также добавили к содержимому метку даты, чтобы клиенты могли определить его актуальность и не выяснять время последнего обновления статьи.

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

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

Глобальная документация

Пользователи из разных стран мира постоянно напоминали нам о важности переведенного содержимого. Теперь сайт docs.Microsoft.com поддерживает 45 языков, включая языки с письмом справа налево, такие как арабский и иврит, а также в общей сложности 63 языковых стандарта для содержимого Dynamics 365 с применением логики перехода на резервную страницу там, где переведенные документы могут быть недоступны. Благодаря этому наша документация становится действительно глобальной и готовой к включению в себя дополнительного содержимого, выходящего в новом году.

Заметки на полях и комментарии

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

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

Чтобы добавить комментарий, выполните вход по существующим учетным данным Twitter, Facebook, Google, Yahoo или Майкрософт.

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

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

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

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

Светлая и темная темы

Мы также добавили средство выбора темы, чтобы можно было переходить между светлой и темной темными темами, которые некоторые из вас имеют [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme).

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

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

До

https://technet.microsoft.com/library/dn646983.aspx3

После

https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune

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

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

Новые возможности сайта документации

Хотя многие из них и появились уже во время запуска в мае, мы добавили несколько новых возможностей, описанных ниже.

Фильтрация оглавления в режиме реального времени

Теперь оглавление поддерживает режим мгновенной фильтрации. Это значит, что, введя всего несколько символов, можно отфильтровать совпадающий текст, чтобы найти нужное содержимое.

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

В целях реализации этой задачи рабочие группы по работе с содержимым получили возможность выбора нужной информации в документах и создания представления этого содержимого для клиентов. На рисунке ниже показан демонстрационный макет, который могли бы использовать разработчики .NET, применяющие Docker. Здесь в одном представлении находятся все материалы, поступающие от команд разработчиков Azure, ASP.NET, .NET Core и пакета SDK Azure для Visual Studio.

Проверяемые примеры кода

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

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

Встроенные справочные материалы

Мы переработали базовый механизм DocFX (компонент с открытым исходным кодом, лежащий в основе docs.microsoft.com), который теперь включает языковые привязки для различных платформ и форматов. Среди прочего, поддерживаются следующие шрифты:

Интерфейс командной строки Azure (Python)
PowerShell
.NET и .NET Core
Java
Swagger/REST API

Это значит, что синхронизация документации с возможностями API больше не должна нарушаться, так как теперь существует один источник истины, являющийся основой для документов и кода. Дополнительные сведения о конкретной поддержке справочников по API можно найти в разделах Azure и ASP.NET/EF ниже.

Поддержка формата PDF

Еще одной важной функцией, о добавлении которой просили клиенты, является поддержка формата PDF. Вы можете скачать определенный набор документов, не занимая много дискового пространства, и использовать его где угодно — как на настольном ПК, так и на мобильном устройстве.

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

<img alt="Снимок экрана 16]()

Документация по Azure

Мы приняли во внимание ваши отзывы о фрагментации и связанных с ней трудностях, поэтому хотим сообщить об успешной работе над переносом технической документации по Azure с сайтов azure.microsoft.com, MSDN и GitHub и ее консолидацией в разделе https://docs.microsoft.com/azure/.

Новая главная страница Azure

Мы также не оставили без внимания внешний вид целевой страницы содержимого по Azure. Далее перечислен ряд ключевых компонентов страницы.

Вкладка Services (Службы) со списком служб Azure, сгруппированных по категориям.
Вкладка Developer (Разработчик) со списком всех справочных материалов по Azure, касающихся REST API, пакета SDK Azure для .NET, пакету SDK Azure для Java, Azure CLI и Azure PowerShell.
Вкладка Architecture (Архитектура), на которой архитекторы и разработчики могут получить информацию о шаблонах разработки в масштабе облака.

Новые страницы для конкретных служб

Мы обеспечили согласованность целевых страниц и разместили на них ссылки на ключевые ресурсы, в том числе:

ссылку Service Overview (Обзор службы);
руководства Приступая к работе для всех нужных платформ и языков программирования;
ссылку на все обучающие видеоматериалы по конкретной службе;
ссылки на справочники по API;
ссылку на скачивание всей документации по службе.

Новое оглавление

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

Улучшенная цветовая схема

Для примеров кода, представляющих интерфейс командной строки (CLI) Azure, добавлено выделение цветом ключевых слов и параметров, что упрощает чтение и понимание кода.

Улучшения в области справочной информации

Нам известно, что одной из серьезнейших проблем является отсутствие актуальных материалов по API, командной строке и PowerShell. Наши устаревшие выполняемые вручную рабочие процессы не соответствуют быстрому темпу изменений Azure и не работают.

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

Мы также переходим на стандартизованное использование спецификации Open API (прежнее название — Swagger) для описания наших REST API, благодаря чему мы получим согласованное представление данных для служб REST, которое может использоваться в документации, а также для клиентских пакетов SDK. В будущем мы добавим интерактивные возможности в нашу документацию по REST и примеры полезных данных для запросов и ответов.

В этот выпуск входят:

Документация по версии-кандидату Visual Studio 2017

Мы представляем всю документацию по Visual Studio, напрямую интегрированную в новый и модернизированный сайт docs.microsoft.com.

Новая главная страница Visual Studio

На главной странице Visual Studio находятся ключевые ссылки на действия по началу работы с версией-кандидатом Visual Studio 2017.

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

Теперь, когда Visual Studio поддерживает процесс полностью настраиваемой установки с использованием только требуемых компонентов, вы можете более подробно узнать, как он применим к вашим конкретным проектам разработки (независимо от того, какая платформа необходима для выполнения рабочих нагрузок, — ASP.NET, Azure, Python или Windows).

Документация по ASP.NET Core и Entity Framework Core

Документация по ASP.NET Core и Entity Framework Core также перенесена с сайта docs.asp.net и GitHub соответственно.

Справочная информация по ASP.NET и Entity Framework

Поскольку ASP.NET Core и Entity Framework Core являются проектами с открытым исходным кодом, мы глубоко интегрировали их исходный код и начинающиеся с трех символов косой черты комментарии для создания справочной документации по их API. Это значит, что API и документация всегда будут синхронизироваться автоматически.

Документация по C++

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

Кроме того, вы можете получить дополнительные сведения о последних изменениях для обеспечения соответствия стандартам C++ и узнать о новых вариантах сборок, таких как /fastlink; воспользоваться новыми рекомендациями по переносу, чтобы обновить код из предыдущих версий Visual Studio; и выяснить, как опробовать новую возможность — разработку в системах Linux при помощи gcc.

Документация по SQL в Linux

SQL Server на платформе Linux (в составе SQL Server vNext Customer Technical Preview 1) уже доступен; вы можете опробовать его. На главной странице находятся ключевые ссылки, позволяющие перейти от действий по началу работы к задачам по управлению и разработке при помощи SQL Server на платформе Linux. Выход переведенного содержимого ожидается в ближайшее время.

Выводы

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

Ноябрьское обновление docs.microsoft.com

В этой публикации

Ключевые возможности сайта документации