Skip to content

Latest commit

 

History

History
154 lines (96 loc) · 15 KB

CONTRIBUTING.md

File metadata and controls

154 lines (96 loc) · 15 KB

Внесите свой вклад в документацию по ASP.NET

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

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

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

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

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

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

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

Расширение "Пакет создания документов" в Visual Studio Code

Если вы используете Visual Studio Code для участия в разработке документации ASP.NET, вы можете повысить производительность, установив расширение Пакет создания документов. Данное расширение предоставляет широкий набор средств, упрощающий проверку формата Markdown, проверку орфографии кода и создание статей по шаблонам.

Синтаксис Markdown

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

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

Для каждого файла Markdown могут существовать папка для изображений и папка для примера кода. Если это статья в виде файла fundamentals/configuration/index.md, изображения находятся в папке fundamentals/configuration/index/_static, а пример файлов проекта приложения — в папке fundamentals/configuration/index/sample. Изображение в файле fundamentals/configuration/index.md обрабатывается по следующим правилам Markdown:

![description of image for alt attribute](configuration/index/_static/imagename.png)

Все изображения должны иметь замещающий текст. Советы по заданию замещающего текста см. в сетевых ресурсах, например WebAIM: замещающий текст.

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

Внутренние ссылки

Внутренние ссылки должны использовать uid целевой статьи со ссылкой xref (текст ссылки задается по заголовку связанного содержимого):

<xref:uid_of_the_topic>

Если заголовок статьи не подходит для текста ссылки (например, слово или фраза в предложении является текстом ссылки), укажите ссылку xref и текст ссылки следующим образом:

[link text](xref:uid_of_the_topic)

Дополнительные сведения см. в разделе Перекрестные ссылки DocFX.

Изображения и снимки экрана

Не включайте изображения в статьи, за исключением следующих случаев:

  • если создаются базовые руководства по внедрению (для начинающих);
  • если изображение необходимо для понимания.

Эти ограничения позволяют уменьшить размер репозитория.

В качестве дополнительного шага убедитесь, что все изображения и снимки экрана в документации сжаты, чтобы не увеличивать размер файла и время загрузки страницы. Среди популярных — средства TinyPNG (веб-сайт TinyPNG или API TinyPNG) или расширение Visual Studio Image Optimizer.

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

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

В следующих примерах показан синтаксис фрагмента кода DFM для использования в файле configuration/index.md.

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

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

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

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

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

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

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

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

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

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

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

DocFX требует:

  • .NET Framework на Windows.
  • Mono для Linux или macOS.

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

  • Скачайте и распакуйте docfx.zip из выпусков DocFX.

  • Добавьте DocFX в PATH.

  • В окне командной строки перейдите в соответствующую папку, содержащую файл docfx.json (aspnet для содержимого ASP.NET или aspnetcore для содержимого ASP.NET Core ) и выполните следующую команду:

    docfx --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 в каталоге Docs\aspnet или Docs\aspnetcore для создания сайта. Запустите docfx-serve для просмотра сайта по адресу http://localhost:8080.

Стиль

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

Руководство по стилю Майкрософт

Руководство по стилю Майкрософт предоставляет рекомендации по стилю и терминологии для всех технических текстов, включая документацию по ASP.NET Core.

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

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