Прочитать на английском

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

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

  • Статья

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы внести свой вклад с помощью этого метода, ознакомьтесь со следующими статьями:

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

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

Если ваши изменения приняты, ваше имя будет указано в качестве участника в начале статьи.

Снимок экрана признания вклада в создание контента.

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

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

Важно!

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

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

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

Включенные в область применения элементы

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

Рассмотрим следующий пример Markdown, который подключает include-файл в 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 для ссылки include applies-to (можно отменить редактирование без отправки изменений).
  • Выполните поиск файлов в каталоге docs/includes, содержащих текст 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.

Спасибо!