Знакомство с документацией по .NET Core

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

Сегодня состоялся выпуск предварительной версии документации по .NET на сайте docs.microsoft.com. Дополнительные сведения о новой документации, включая описание улучшений, доступны на сайте docs.microsoft.com в соответствующей записи блога. В дополнение ко всем функциям совместной работы, содержимому с открытым кодом и удобным URL-адресам, доступных на платформе docs.microsoft.com, мы предоставили несколько новых функций, предназначенных для разработчиков .NET. В данной записи мы опишем эти новые функции, а также поделимся планами на будущее.

Важные аспекты при работе с документацией по .NET

Чтобы оповестить пользователей о выпуске RTM .NET Core, мы разместили сведения о нем в центре главной страницы документации .NET. Чтобы дополнить выпуск RTM .NET Core всем тем, что потребуется для быстрого начала работы, мы разместили ссылки на статьи и новый ссылочный интерфейс в верхней части списка.

Домашняя страница документации по .NET

Экосистема .NET у вас под рукой

Вы увидите ссылки для скачивания новых библиотек .NET Core, ASP.NET, Entity Framework, Azure, на использование Xamarin для создания приложений iOS с помощью .NET и создание приложений универсальной платформы Windows (UWP) с помощью .NET. Мы пока не перенесли все содержимое .NET на сайт docs.microsoft.com, но домашняя страница документации по .NET станет отправной точкой для доступа ко всей документации по .NET.

Ссылки на разделы документации по .NET

Статьи

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

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

Статьи и руководства

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

Нажмите кнопку

Для редактирования статьи достаточно нажать кнопку "Изменить" в любом из файлов Markdown в репозитории, добавить содержимое и отправить запрос на вытягивание. После того, как наша команда проверит и примет ваш запрос на вытягивание, ваши правки будут внесены на сайт в считаные минуты.

После этого можно редактировать содержимое прямо в GitHub.

Справочник по API

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

Представление пространств имен ссылок

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

Гибкий дизайн в ссылках

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

Представление пространств имен ссылок

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

Представление классов

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

Представление методов

Принципы обработки информации и проектирования

Кроме постоянной разработки и улучшения средств создания документов DocFX, мы внесли значительные усовершенствования в принципы проектирования и документирования, которые вы наверняка заметите в новом интерфейсе документации .NET.

Улучшенная автоматизация

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

Улучшенные URL-адреса

Одним из важных принципов работы всего интерфейса docs.microsoft.com являются усовершенствованные URL-адреса, улучшающие индексирование поиска и использование "предположений". Этот принцип сохранен в документации по .NET. Как в статьях, так и в справочной документации используются более понятные URL-адреса. Возьмем, например, классический URL-адрес MSDN для пространства имен System:

URL-адрес пространства имен System на MSDN

В новой справочной документации URL-адрес является более логичным, понятным для человека и, что наиболее важно, лучше обнаруживаемым.

URL-адрес пространства имен System на docs.microsoft.com

Более гибкая и открытая разработка

Содержимое представлено не только открытым кодом, и мы принимаем не только материалы сообщества. Кроме того, все содержимое на сайте docs.microsoft.com (включая документацию по .NET) доступно по лицензии Creative Commons. Вы можете прочитать его, скопировать, сослаться на него и повторно использовать его части (даже в коммерческих целях). Писатели и инженеры активно работали с членами сообщества в этой новой системе в течение нескольких месяцев. Это был интересный и увлекательный переход, и в будущем мы собираемся снова сделать нечто подобное.

Планы на будущее

Этот раздел сайта docs.microsoft.com, как и остальная его часть, по-прежнему находится на этапе предварительной версии, поэтому мы собираем конструктивные отзывы и комментарии. Поделитесь своими идеями о функциях через UserVoice.

В предстоящие недели мы будем публиковать комментарии XML, которые используются для создания справочной документации, непосредственно в исходном коде .NET. Это позволит любому пользователю легко обновить справочную документацию по .NET Framework.
Кроме того, мы продолжим настраивать структуру и макет ссылки, а также вышеуказанную возможность редактирования справочного содержимого.

Мы рады представить вам новую область документации по .NET на сайте docs.microsoft.com и надеемся, что в будущем сможем предложить вам еще более удобные условия работы.