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

Как внести свой вклад в документацию по SQL Server

  • Статья

Область применения: SQL Server База данных SQL Azure Azure Synapse Analytics Analytics Platform System (PDW)

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

Существуют два основных процесса работы над документацией:

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

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

Редактирование в браузере

Можно вносить простые изменения в содержимое в SQL Server через браузер и отправлять их в корпорацию Майкрософт. Дополнительные сведения см. в обзоре руководства для соавторов.

Этот процесс состоит из следующих шагов.

  1. На странице с отзывом выберите значок карандаша в правом верхнем углу.
  2. На следующей странице щелкните значок карандаша в правом верхнем углу. Если этот значок не отображается, вам может потребоваться сначала войти в учетную запись GitHub.
  3. На следующей странице в текстовом окне Правка файла внесите изменения непосредственно в текст, который требуется изменить. Если вам нужна помощь с форматированием нового или измененного текста, см памятку по разметке.
  4. После внесения изменений в разделе "Фиксация изменений" выполните следующие действия:
    1. В первом текстовом поле введите краткое описание внесенных изменений.
    2. В поле Добавить необязательное расширенное описание введите краткое объяснение изменений.
  5. Выберите Предложить изменение файла.
  6. На странице Сравнение изменений выберите Создать запрос на вытягивание.
  7. На странице Открыть запрос на вытягивание выберите Создать запрос на вытягивание.

В следующем GIF-файле показан весь процесс отправки изменений в браузере.

Снимок экрана: изменение документов SQL.

Локальное редактирование с помощью средств

Другой вариант редактирования — вилку sql-docs или azure-docs репозитории и клонировать их локально на компьютер. После этого можно использовать редактор Markdown и клиент GIT для отправки изменений. Такой способ подходит для более сложных правок или правок, охватывающих несколько файлов. Это также хорошо для частых участников технической документации Майкрософт.

Сведения об использовании этого метода см. в следующих статьях:

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

Распознавание

Если изменения принимаются, вы признаны участником в верхней части статьи.

Снимок экрана: распознавание вклада содержимого.

Общие сведения о SQL-docs

В этом разделе приведены дополнительные рекомендации по работе в репозитории sql-docs .

Внимание

Сведения в этом разделе относятся к sql-docs. Если вы редактируете статью SQL в документации Azure, ознакомьтесь с разделом Readme для репозитория azure-docs на сайте GitHub.

Содержимое в репозитории sql-docs упорядочивается по нескольким стандартным папкам.

Папка Description
Документация Содержит все опубликованное содержимое по SQL Server. Разделы содержимого логически упорядочиваются по вложенным папкам.
docs/includes Содержит включаемые файлы. Эти файлы представляют собой блоки содержимого, которое можно включить в одну или несколько других статей.
./media Каждая папка может содержать одну media вложенную папку для изображений статей. В media папке, в свою очередь, есть вложенные папки с тем же именем, что и статьи, в которые отображается изображение. Изображения должны быть в формате PNG, а их имена должны содержать только символы в нижнем регистре без пробелов.
TOC.MD Файл содержания. В каждой вложенной папке может использоваться один файл TOC.MD.

Включаемые файлы applies-to

Каждая статья SQL Server содержит applies-to файл включения после заголовка. Он указывает, к каким областям или версиям SQL Server относится статья.

Рассмотрим следующий пример Markdown, который извлекает в applies-to-version/sql-asdb-asa-pdw.md файл включения.

[!INCLUDE [SQL Server Azure SQL Database Synapse Analytics PDW](../includes/applies-to-version/sql-asdb-asdbmi-asa-pdw.md)]

Он добавляет следующий текст в начало статьи:

Снимок экрана: область применения к тексту.

Чтобы найти подходящий включаемый файл applies-to для статьи, следуйте приведенным ниже советам.

  • Список часто используемых включает в себя файлы SQL Server для управления версиями и применения.
  • Просмотрите другие статьи, посвященные той же функции или связанной задаче. Вы можете начать редактировать эту статью и скопировать разметку Markdown ссылки на включаемый файл applies-to (отменить редактирование можно, не отправляя изменений).
  • Выполните поиск в каталоге для файлов, содержащих текст applies-to. Чтобы быстро отфильтровать файлы, можно использовать кнопку Найти в GitHub. Выберите файл, чтобы узнать, как он отрисовывается.
  • Обратите внимание на соглашение об именовании. Если имя содержит несколько x символов в строке, они обычно заполнители, указывающие на отсутствие поддержки службы. Например, appliesto-xx-xxxx-asdw-xxx-md.md указывает на поддержку только Azure Synapse Analytics, так как указаны только asdw другие поля x.
  • Некоторые включают указание номера версии, например tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. Используйте только эти файлы, если вы знаете, что эта функция появилась с определенной версией SQL Server.

Ресурсы для участников

Совет

Если вы хотите оставить отзыв по продукту SQL Server, а не по документации, это можно сделать здесь.

Связанный контент

Изучите репозиторий sql-docs в GitHub.

Найдите статью и отправьте изменение, чтобы помочь сообществу SQL Server.

Спасибо!