Guide pratique pour contribuer à la documentation SQL Server

  • Article

S’applique à : SQL Server Base de données Azure SQL Azure Synapse Analytics Analytics Platform System (PDW)

Tout le monde peut apporter sa contribution à la documentation SQL Server. C’est-à-dire corriger des fautes de frappe, suggérer de meilleures explications et améliorer la précision technique. Cet article explique comment commencer à contribuer à du contenu et comment fonctionne la procédure.

Il existe deux flux de travail principaux que vous pouvez utiliser pour apporter votre contribution :

Workflow Description
Modifier dans votre navigateur Recommandé pour les modifications mineures et rapides d’un article.
Modifier localement avec des outils Convient pour les modifications plus complexes, les modifications impliquant plusieurs articles et les contributions fréquentes.

L'équipe du contenu SQL valide toutes les contributions publiques pour s'assurer de leur exactitude technique et de leur cohérence.

Modifier dans votre navigateur

Vous pouvez apporter des modifications de base au contenu SQL Server dans votre navigateur, puis les envoyer à Microsoft. Pour plus d’informations, consultez la vue d’ensemble du guide du contributeur.

Les étapes suivantes montrent la procédure à suivre :

  1. Dans la page sur laquelle vous souhaitez laisser des commentaires, sélectionnez l’icône du Crayon en haut à droite.
  2. Dans la page suivante, sélectionnez l’icône en forme de crayon en haut à droite. Si cette icône n’apparaît pas, vous devrez peut-être d’abord vous connecter à votre compte GitHub.
  3. Dans la page suivante, dans la fenêtre de texte Edit file (Modifier le fichier), apportez vos modifications directement dans le texte. Si vous avez besoin d’aide pour mettre en forme le texte que vous ajoutez ou celui que vous changez, consultez l’aide-mémoire sur Markdown.
  4. Une fois que vous avez apporté vos modifications, sous Commit changes (Valider les changements) :
    1. Dans la première zone de texte, entrez une brève description du changement que vous apportez.
    2. Dans la zone Add an optional extended description (Ajouter une description étendue facultative), entrez une brève explication de votre changement.
  5. Sélectionnez Propose file change (Proposer un changement de fichier).
  6. Dans la page Comparing changes (Comparaison des changements), sélectionnez Create pull request (Créer une demande de tirage).
  7. Dans la page Open a pull request (Ouvrir une demande de tirage), sélectionnez Create pull request (Créer une demande de tirage).

L’image GIF suivante montre le processus de bout en bout pour soumettre des changements dans votre navigateur :

Capture d’écran de la modification de SQL Docs.

Modifier localement avec des outils

Une autre option de modification consiste à dupliquer les référentiels sql-docs ou azure-docs, puis à les cloner localement sur votre ordinateur. Vous pouvez ensuite utiliser un éditeur Markdown et un client Git pour soumettre les modifications. Ce flux de travail est approprié pour les modifications plus complexes ou qui impliquent plusieurs fichiers. Il convient aussi pour les contributeurs fréquents à la documentation technique de Microsoft.

Pour apporter votre contribution à l’aide de cette méthode, consultez les articles suivants :

Si vous envoyez une demande de tirage avec d’importants changements à apporter à la documentation, un commentaire s’affiche dans GitHub vous demandant d’envoyer un contrat de licence de contribution (CLA, Contribution License Agreement) en ligne. Pour que votre demande de tirage soit acceptée, vous devez au préalable compléter le formulaire en ligne.

Reconnaissance

Si vos changements sont acceptés, vous êtes reconnu comme contributeur en haut de l’article.

Capture d’écran de la reconnaissance des contributions de contenu.

Vue d’ensemble de SQL-docs

Cette section fournit plus d’informations sur l’utilisation du référentiel sql-docs.

Important

Les informations de cette section sont spécifiques à sql-docs. Si vous modifiez un article SQL dans la documentation Azure, consultez le fichier Lisez-moi du référentiel azure-docs sur GitHub.

Le référentiel sql-docs utilise plusieurs dossiers standard pour organiser le contenu.

Dossier Description
docs Contient tout le contenu SQL Server publié. Les sous-dossiers organisent de manière logique les différents domaines du contenu.
docs/includes Contient les fichiers include. Ces fichiers sont des blocs de contenu qui peuvent être inclus dans un ou plusieurs autres articles.
./media Chaque dossier peut avoir un sous-dossier media pour les images des articles. Le dossier media comprend à son tour des sous-dossiers portant le même nom que les articles dans lesquelles l’image apparaît. Les images doivent être des fichiers .png avec toutes les lettres en minuscules et sans espaces.
TOC.MD Fichier de table des matières. Chaque sous-dossier a la possibilité d’utiliser un fichier TOC.MD.

Fichiers include Applies-to

Chaque article SQL Server contient un fichier include applies-to après le titre. Cela indique les domaines ou les versions de SQL Server auxquels l’article s’applique.

Prenons l’exemple Markdown suivant qui récupère le fichier 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)]

Cette opération ajoute le texte suivant en haut de l’article :

Capture d’écran de S’applique au texte.

Pour trouver le fichier include applies-to approprié à votre article, utilisez les conseils suivants :

  • Pour une liste de fichiers include couramment utilisés, consultez les fichiers include SQL Server pour le contrôle de version et applies-to.
  • Consultez d’autres articles qui traitent de la même fonction ou d’une tâche associée. Si vous modifiez cet article, vous pouvez copier le texte Markdown du lien du fichier include applies-to (vous pouvez annuler la modification sans la soumettre).
  • Recherchez les fichiers contenant le texte applies-to dans l’annuaire docs/includes. Vous pouvez utiliser le bouton Find (Trouver) dans GitHub pour appliquer rapidement un filtre. Sélectionnez le fichier pour voir comment il est rendu.
  • Faites attention à la convention de nommage. Si le nom contient plusieurs caractères x dans la chaîne, ce sont généralement des espaces réservés qui indiquent l'absence de prise en charge d'un service. Par exemple, appliesto-xx-xxxx-asdw-xxx-md.md indique la prise en charge d’Azure Synapse Analytics uniquement, car seul asdw est indiqué clairement, tandis que les autres champs contiennent des x.
  • Certains fichiers include spécifient un numéro de version, tel que tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. Utilisez ces fichiers include seulement si vous savez que la fonctionnalité a été introduite avec une version spécifique de SQL Server.

Ressources pour les contributeurs

Conseil

Si vous avez des commentaires sur le produit plutôt que sur la documentation, fournissez vos commentaires sur le produit SQL Server ici.

Contenu connexe

Explorez le référentiel sql-docs sur GitHub.

Recherchez un article, envoyez une modification et aidez la Communauté SQL Server.

Merci !