Come contribuire alla documentazione di SQL Server

  • Articolo

Si applica a: SQL ServerDatabase SQL di AzureAzure Synapse AnalyticsPiattaforma di strumenti analitici (PDW)

Chiunque può contribuire alla documentazione di SQL Server. Si può contribuire, ad esempio, correggendo gli errori tipografici, suggerendo spiegazioni più chiare e migliorando la precisione dal punto di vista tecnico. Questo articolo illustra come iniziare a contribuire al contenuto e come funziona il processo.

Si può contribuire alla documentazione usando due flussi di lavoro principali:

Flusso di lavoro Descrizione
Apportare modifiche nel browser Adatto per piccole e rapide modifiche degli articoli.
Apportare modifiche a livello locale con gli strumenti Adatto per modifiche più complesse, modifiche che interessano più articoli e contributi frequenti.

Tutti i contributi pubblici vengono convalidati dal team responsabile dei contenuti relativi a SQL per garantirne la coerenza e l'accuratezza tecnica.

Apportare modifiche nel browser

È possibile apportare semplici modifiche al contenuto SQL Server nel browser e quindi inviarle a Microsoft. Per altre informazioni, vedere la panoramica della guida per i collaboratori.

La procedura seguente sintetizza il processo:

  1. Nella pagina su cui si hanno commenti, selezionare l'icona Matita in alto a destra.
  2. Nella pagina successiva selezionare l'icona Matita in alto a destra. Se questa icona non viene visualizzata, potrebbe essere necessario accedere prima all'account GitHub.
  3. Nella finestra Edit file text (Modifica testo file) nella pagina successiva apportare le modifiche direttamente al testo che si vuole modificare. Se è necessaria assistenza per la formattazione del testo nuovo o modificato, vedere Markdown Cheatsheet (Scheda di riferimento rapido per il markdown).
  4. Dopo aver apportato le modifiche, in Conferma modifiche:
    1. Nella prima casella di testo immettere una breve descrizione della modifica che si apporta.
    2. Nella casella Add an optional extended description (Aggiungi descrizione estesa facoltativa) immettere una breve descrizione della modifica.
  5. Selezionare Propose file change (Proponi modifica file).
  6. Nella pagina Comparing changes (Confronto modifiche) selezionare Create pull request (Crea richiesta pull).
  7. Nella pagina Open a pull request (Apri richiesta pull) selezionare Create pull request (Crea richiesta pull).

Il video seguente illustra la procedura completa per l'invio delle modifiche nel browser:

Screenshot of Edit SQL Docs.

Apportare modifiche a livello locale con gli strumenti

Un'altra opzione di modifica è creare un fork del repository sql-docs o azure-docs e clonarlo nel computer locale. È quindi possibile usare un editor di Markdown e un client Git per inviare le modifiche. Questo flusso di lavoro è ottimale per le modifiche più complesse o che interessano più file. È utile anche per i collaboratori frequenti alla documentazione tecnica Microsoft.

Per contribuire con questo metodo, vedere gli articoli seguenti:

Se si invia una richiesta pull con modifiche significative alla documentazione, viene visualizzato un commento in GitHub che richiede di inviare un contratto di licenza per contributi (CLA) online. È necessario completare il modulo online affinché la richiesta pull possa essere accettata.

Riconoscimento

Se le modifiche vengono accettate, l'utente viene riconosciuto come collaboratore all'inizio dell'articolo.

Screenshot of Content contribution recognition.

Panoramica di SQL-docs

Questa sezione fornisce informazioni aggiuntive sull'uso del repository sql-docs.

Importante

Le informazioni di questa sezione sono specifiche per sql-docs. Se si modifica un articolo su SQL nella documentazione di Azure, vedere il file Leggimi relativo al repository azure-docs su GitHub.

Il repository sql-docs usa alcune cartelle standard per organizzare il contenuto.

Cartella Descrizione
Documentazione Contiene tutto il contenuto pubblicato su SQL Server. Le diverse aree del contenuto sono organizzate logicamente in sottocartelle.
docs/includes Contiene i file di inclusione. Questi file sono blocchi di contenuto che si possono includere in uno o più articoli diversi.
./media Ogni cartella può avere una sottocartella media per le immagini degli articoli. La cartella media a sua volta contiene sottocartelle con lo stesso nome degli articoli in cui appare l'immagine. Le immagini devono essere file PNG con tutte le lettere minuscole e senza spazi.
TOC.MD Un file di sommario. Ogni sottocartella può usare un file TOC.MD.

Inclusioni applies-to

Ogni articolo su SQL Server contiene un file di inclusione applies-to dopo il titolo. Indica a quali aree o versioni di SQL Server si riferisce l'articolo.

Si consideri l'esempio di Markdown seguente che esegue il pull nel file di inclusione 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)]

Questo comando aggiunge il testo seguente nella parte superiore dell'articolo:

Screenshot of Applies to text.

Per trovare il file di inclusione applies-to corretto per l'articolo, usare i suggerimenti seguenti:

  • Per un elenco delle inclusioni di uso comune, vedere File di inclusione per il controllo delle versioni e Si applica a in SQL Server.
  • Consultare un altro articolo che analizza la stessa funzionalità o un'attività correlata. Se si modifica quell'articolo, è possibile copiare il Markdown per il collegamento al file di inclusione applies-to (è possibile annullare la modifica senza inviarla).
  • Cercare nella directory docs/includes i file che contengono il testo applies-to. È possibile usare il pulsante Find in GitHub per filtrare rapidamente. Selezionare il file per vedere come esegue il rendering.
  • Prestare attenzione alla convenzione di denominazione. Se il nome contiene più caratteri x nella stringa, in genere sono segnaposto che indicano la mancanza di supporto per un servizio. Ad esempio, appliesto-xx-xxxx-asdw-xxx-md.md indica che esiste solo il supporto per Azure Synapse Analytics, poiché nel nome appare solo asdw, mentre gli altri campi contengono solo x.
  • Alcuni includono specificare un numero di versione, ad esempio tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. Usare questi file di inclusione solo quando si sa cha la funzionalità è stata introdotta con una versione specifica di SQL Server.

Risorse per i collaboratori

Suggerimento

Per inviare commenti e suggerimenti relativi al prodotto anziché alla documentazione, inserire qui eventuali suggerimenti per il prodotto SQL Server.

Contenuto correlato

Esplorare il repository sql-docs su GitHub.

Trovare un articolo, inviare una modifica e collaborare con la community di SQL Server.

Grazie.