Como contribuir com a documentação do SQL Server

  • Artigo

Aplica-se a: SQL Server Banco de Dados SQL do Azure Azure Synapse Analytics PDW (Analytics Platform System)

Qualquer pessoa pode contribuir para a documentação do SQL Server. Isso inclui corrigir erros de digitação, sugerir melhores explicações e melhorar a precisão técnica. Este artigo explica como começar com as contribuições de conteúdo e como o processo funciona.

Há dois fluxos de trabalho principais que você pode usar para contribuir:

Fluxo de trabalho Descrição
Editar no navegador Bom para edições simples e breves de qualquer artigo.
Editar localmente com ferramentas Bom para edições mais complexas, edições que envolvem vários artigos e contribuições frequentes.

A equipe de conteúdo do SQL valida todas as contribuições públicas quanto à precisão técnica e à consistência.

Editar no navegador

Você pode fazer edições simples no conteúdo do SQL Server em seu navegador e, em seguida, enviá-las à Microsoft. Para obter mais informações, confira o guia do colaborador do Microsoft Docs.

O processo é resumido pelas seguintes etapas:

  1. Na página sobre a qual você tem comentários, selecione o ícone de Pincel no canto superior direito.
  2. Na página seguinte, selecione o ícone de Lápis no canto superior direito. Se esse ícone não aparecer, talvez seja necessário entrar na conta do GitHub primeiro.
  3. Na página seguinte, na janela de texto Editar arquivo, faça suas edições diretamente no texto que deseja alterar. Se precisar de ajuda com a formatação do texto novo ou alterado, consulte a Folha de Referências de Markdown.
  4. Depois de fazer suas edições, em Confirmar alterações:
    1. Na primeira caixa de texto, insira uma breve descrição da alteração feita.
    2. Na caixa Adicionar uma descrição estendida opcional, forneça uma breve explicação de sua alteração.
  5. Selecione Propor alteração de arquivo.
  6. Na página Comparando alterações, selecione Criar solicitação de pull.
  7. Na página Abrir solicitação de pull, selecione Criar solicitação de pull.

O seguinte GIF mostra o processo de ponta a ponta para enviar as alterações ao seu navegador:

Captura de tela de Editar documentos SQL.

Editar localmente com ferramentas

Outra opção de edição é criar fork nos repositórios sql-docs ouazure-docs e cloná-los localmente para seu computador. Dessa forma, você poderá usar um editor de Markdown e um cliente git para enviar as alterações. Este fluxo de trabalho é bom para edições mais complexas ou que envolvem vários arquivos. Ele também é bom para colaboradores frequentes para a documentação técnica da Microsoft.

Para contribuir com esse método, consulte os seguintes artigos:

Se enviar uma solicitação de pull com alterações significativas na documentação, você receberá um comentário no GitHub solicitando o envio de um CLA (contrato de licença de contribuição) online. É necessário preencher o formulário online para que sua solicitação de pull seja aceita.

Reconhecimento

Se as alterações forem aceitas, você será reconhecido como um colaborador na parte superior do artigo.

Captura de tela do Reconhecimento de contribuição de conteúdo.

Visão geral de SQL-docs

Esta seção fornece mais orientações sobre como trabalhar no repositório sql-docs.

Importante

As informações desta seção são específicas para sql-docs. Se você estiver editando um artigo do SQL na documentação do Azure, veja o Leiame do repositório azure-docs no GitHub.

O repositório sql-docs usa várias pastas padrão para organizar o conteúdo.

Pasta Descrição
docs Contém todo o conteúdo publicado do SQL Server. As subpastas organizam logicamente as diferentes áreas do conteúdo.
docs/includes Contém arquivos include. Esses arquivos são blocos de conteúdo que pode ser incluído em um ou mais artigos.
./media Cada pasta pode ter uma subpasta media para imagens do artigo. A pasta media, por sua vez, tem subpastas com o mesmo nome que os artigos nos quais a imagem aparece. As imagens devem ser arquivos .png com todas as letras minúsculas e sem espaços.
TOC.MD Um arquivo de índice. Cada subpasta tem a opção de usar um arquivo TOC.MD.

Includes Applies-to

Cada artigo do SQL Server contém um arquivo include applies-to após o título. Isso indica a quais áreas ou versões do SQL Server o artigo se aplica.

Considere o seguinte exemplo de Markdown que efetua pull no arquivo 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)]

Isso adiciona o seguinte texto à parte superior do artigo:

Captura de tela de texto do Applies to.

Para encontrar o arquivo include applies-to correto para o artigo, use as dicas a seguir:

  • Para obter uma lista dos includes mais usados, veja Arquivos include do SQL Server para controle de versão e applies-to.
  • Examine outros artigos que abordam o mesmo recurso ou uma tarefa relacionada. Se você editar esse artigo, poderá copiar o Markdown para o link do include applies-to (será possível cancelar a edição sem enviá-la).
  • Pesquise no diretório docs/includes para arquivos que contém o texto applies-to. Você pode usar o botão Localizar no GitHub para filtrar rapidamente. Selecione o arquivo para ver como ele é renderizado.
  • Atente-se à convenção de nomenclatura. Se o nome contiver vários caracteres x na cadeia de caracteres, eles geralmente são espaços reservados que indicam a falta de suporte para um serviço. Por exemplo, appliesto-xx-xxxx-asdw-xxx-md.md indica suporte apenas para o Azure Synapse Analytics, porque somente asdw está escrito, enquanto os outros campos mostram xs.
  • Alguns incluem especificar um número de versão, como tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. Use esses arquivos include somente se você conhecer o recurso que foi introduzido em uma versão específica do SQL Server.

Recursos do colaborador

Dica

Se você tiver comentários sobre o produto, em vez de comentários sobre a documentação, deixe seus comentários sobre o produto SQL Server aqui.

Conteúdo relacionado

Explore o repositório sql-docs no GitHub.

Localize um artigo, envie uma alteração e ajude a comunidade do SQL Server.

Obrigado.