Участие в разработке документации по службам IIS

Статья
07/18/2023

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

Как создать простое исправление или предложение

Статьи хранятся в репозитории в виде файлов Markdown. Небольшие изменения содержимого файла Markdown можно внести в браузере, щелкнув ссылку Изменить в правом верхнем углу окна браузера. (В узких окнах браузера необходимо развернуть панель параметров , чтобы увидеть ссылку Изменить .) Следуйте инструкциям, чтобы создать запрос на вытягивание (PR). Мы рассмотрим запрос на вытягивание и примем его или предложим изменения.

Как сделать более сложные правки

Потребуется базовое представление о Git и GitHub.com.

Создайте запрос, описывающий, что нужно сделать, например изменить существующую статью или создать новую. Дождитесь от нас одобрения, прежде чем тратить время.
Создайте вилку репозитория iis-docs и создайте ветвь для изменений.
Отправьте запрос на вытягивание с вашими изменениями в главную ветвь.
Если вашему запросу назначена метка "cla-required", заполните лицензионное соглашение об участии (CLA)
Ответьте на обратную связь по запросу на вытягивание.

Пример, в котором этот процесс привел к публикации новой статьи, см. в проблеме 67 и запросе на вытягивание 798 в репозитории .NET. Новая статья — Документирование кода.

Синтаксис Markdown

Статьи написаны в формате DocFx-flavored Markdown, который представляет собой расширенную версию GitHub-flavored Markdown (GFM). Примеры синтаксиса DFM для функций пользовательского интерфейса, часто используемых в документации, см. в разделе Метаданные и шаблон Markdown в руководстве по стилю репозитория .NET.

Соглашения о структуре папок

Для каждого файла Markdown может быть папка для изображений и папка для примера кода. Например, если статья — /extensions/advanced-logging-module/advanced-logging-for-iis-client-logging.md, образы находятся в файле extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/_static а файлы проекта примера приложения находятся в файле extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/samples. Изображение в файле /advanced-logging-for-iis-client-logging.md отображается с помощью следующего markdown.

![description of image for alt attribute](advanced-logging-for-iis-client-logging/_static/imagename.png)

Все изображения должны иметь замещающий текст.

Имена файлов Markdown и изображений должны быть в нижнем регистре.

Фрагменты кода

Статьи часто содержат фрагменты кода для иллюстрации. DFM позволяет копировать код в файл Markdown или ссылаться на отдельный файл кода. Рекомендуется использовать отдельные файлы кода, когда это возможно, чтобы свести к минимуму вероятность ошибок в коде. Файлы кода следует хранить в репозитории в соответствии со структурой папок, описанной ранее для образцов проектов.

Ниже приведены некоторые примеры синтаксиса фрагмента кода DFM , который будет использоваться в configuration.md файле.

Для отображения всего файла кода в виде фрагмента:

[!code-csharp[Main](configuration/sample/Program.cs)]

Для подготовки к просмотру части файла как фрагмента с помощью номеров строк:

[!code-csharp[Main](configuration/sample/Program.cs?range=1-10,20,30,40-50]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=1-10,20,30,40-50]

Для фрагментов C# можно ссылаться на область C#. По возможности используйте области, а не номера строк, так как номера строк в файле кода, как правило, меняются и теряют синхронизацию с номерами строк в Markdown. Области C# могут быть вложенными, и если вы ссылаетесь на внешнюю область, внутренняя область #region и директивы #endregion не отображаются во фрагменте.

Для подготовки области C# с именем "snippet_Example":

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example)]

Чтобы выделить выбранные строки в готовом для просмотра фрагменте кода (обычно выделяются желтым цветом):

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]
[!code-csharp[Main](configuration/sample/Program.cs?range=10-20&highlight=1-3]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=10-20&highlight=1-3]
[!code-javascript[Main](configuration/sample/Project.json?range=10-20&highlight=1-3]

Тестирование изменений с помощью DocFX

Протестируйте изменения с помощью средства командной строки DocFX, которое создает локально расположенную версию сайта. DocFX не отображает стили и расширения сайта, созданные для learn.microsoft.com.

Для работы с DocFX требуется .NET Framework в Windows или Mono (для Linux или macOS).

Инструкции для Windows

Скачайте и распакуйте docfx.zip из выпусков DocFX.
Добавьте DocFX в PATH.
В окне командной строки перейдите в соответствующую папку, содержащую файл docfx.json (iis-docs/iis), и выполните следующую команду:
```
docfx -t default --serve
```
В браузере перейдите на адрес http://localhost:8080.

Инструкции для Mono

Установите Mono через Homebrew: brew install mono.
Загрузите последнюю версию DocFX.
Извлеките в \bin\docfx.

Создайте псевдоним для docfx:

function docfx {
  mono $HOME/bin/docfx/docfx.exe
}

function docfx-serve {
  mono $HOME/bin/docfx/docfx.exe serve _site
}

Запустите docfx в каталоге iis-docs\iis, чтобы создать сайт, и docfx-serve , чтобы просмотреть сайт по адресу http://localhost:8080.

Стиль и тон

Наши документы должны быть понятными для самой широкой аудитории. С этой целью мы разработали рекомендации по стилю и просим наших авторов следовать им. Дополнительные сведения см. в разделе Рекомендации по стилю в репозитории .NET.

Перенаправления

Если вы удалите статью, измените ее имя или переместите ее в другую папку, создайте перенаправление, чтобы пользователи, создавшие закладки, не получили 404s. Добавьте перенаправление в главный файл перенаправления.

Поделиться через