Skip to content

sql-server-docs-contribute.md

Latest commit

 

History

History
133 lines (85 loc) · 7.56 KB

sql-server-docs-contribute.md

File metadata and controls

133 lines (85 loc) · 7.56 KB
title How to Contribute to SQL Server Documentation | Microsoft Docs
ms.date 03/12/2018
ms.prod sql-non-specified
ms.prod_service sql-non-specified
ms.service
ms.component sql-non-specified
ms.reviewer
ms.suite sql
ms.custom
ms.technology
ms.tgt_pltfrm
ms.topic article
author rothja
ms.author jroth
manager craigg
ms.workload Active

How to contribute to SQL Server Documentation

[!INCLUDEappliesto-ss-asdb-asdw-pdw-md.md]

Anyone can contribute to SQL Server documentation. This includes correcting typos, suggesting better explanations, and improving technical accuracy. This article explains how to get started with content contributions and how the process works.

There are two main workflows.

Editing workflow Good for...
Edit in your browser Small, quick edits of any topic.
Edit locally with tools More complex edits, edits involving multiple files, and frequent contributions to docs.microsoft.com.

Edit in your browser

The following steps provide an overview of making simple edits to SQL erver content in your browser. The complete process is documented in the article, GitHub contribution workflow for minor or infrequent changes.

  1. Every article, including this one, has an Edit button on the right. Click Edit to get started.

    Edit button for SQL article

    All of the content on docs.microsoft.com is managed in various GitHub Repositories. When you click the edit button, you are taken to the article in either the sql-docs or azure-docs repositories depending on the topic you are editing.

  2. Next, click on the pencil icon at the top-right of the article in GitHub.

    Edit button

    [!NOTE] You must be signed in to GitHub to edit an article. If you do not have a GitHub account, see GitHub account setup. After creating a new account, you must also verify your email address with GitHub before you can edit.

  3. Edit the article in the browser. All of the articles are written in Markdown. If you need help with Markdown, you can review Markdown basics. You can also learn by observing how published articles render existing Markdown.

  4. Scroll down to the bottom of the edit window, enter a title for your change, and click the green Propose file change button.

  5. On the next page, click Create pull request.

  6. Enter a title and description for the pull request. Then click Create pull request again.

At this point, you should be guided through the rest of the process in the comments of the pull request. The complete process and additional details can be found in the contributor guide.

Edit locally with tools

Another editing option is to fork the sql-docs or azure-docs repositories and clone it locally to your machine. You can then use a Markdown editor and a git client to submit the changes.

To contribute with this method, see the following articles:

If you submit a pull request with significant changes to documentation, you will get a comment in GitHub asking you to submit an online Contribution License Agreement (CLA). You must complete the online form before your pull request can be accepted.

Tip

This is a good option for large submissions, such as a change involving multiple articles. It is also useful for frequent contributors. For small or infrequent changes, use the GitHub UI.

SQL Server documentation guidance

This section provides some additional guidance on working in the sql-docs repository.

Important

The informartion in this section is specific to sql-docs. If you are editing a SQL topic in the Azure documentation, see the Readme for the azure-docs repository on GitHub.

Repository basics

The sql-docs repository uses several standard folders to organize the content.

Folder Description
docs Contains all published SQL Server content. Subfolders logically organize different areas of the content.
docs/includes Contains include files. These are portions of content that can be included in one or more other topics.
./media Contains article images are in various media subfolders relative to the article location.
TOC.MD Table of contents file in each subfolder.

Applies-to includes

Each SQL Server article contains an applies-to include file after the title. This indicates what areas or versions of SQL Server the article applies to.

Consider the following Markdown example that pulls in the appliesto-ss-asdb-asdw-pdw-md.md include file.

[!INCLUDE[appliesto-ss-asdb-asdw-pdw-md](../includes/appliesto-ss-asdb-asdw-pdw-md.md)]

This adds the following text at the top of the article:

Applies to text

To find the correct applies-to include for your article, use the following tips:

  • Look at other articles that cover the same feature or a related task. If you edit that article, you can copy the Markdown for the applies-to include link (you can cancel the edit without submitting it).
  • Search the docs/includes directory for files containing the text "applies-to". You can use the Find button in github to quickly filter. Click on the file to see how it is rendered.
  • Pay attention to the naming convention. If there are x's in the name, they are usually placeholders indicating the lack of support for a service. For example, appliesto-xx-xxxx-asdw-xxx-md.md indicates support for only Azure SQL Data Warehouse, because only asdw is spelled out, whereas the other fields have x's.
  • Some includes specify a version number, such as tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. Only use these when you know the feature was introduced with a specific version of SQL Server.

Contributor resources

Tip

If you have product feedback rather than documentation feedback, provide feedback on the SQL Server product here.

Next steps

Explore the sql-docs repository on GitHub.

Find an article, submit a change, and help the SQL Server community.

Thank you!