Partager via

Liste de contrôle de l’éditeur

Cet article contient une liste résumée de règles pour l’écriture ou la modification de la documentation PowerShell. Consultez d’autres articles du Guide du contributeur pour obtenir des explications détaillées et des exemples de ces règles.

Métadonnées

  • ms.date: doit être au format MM/DD/AAAA
    • Modifier la date d’une mise à jour significative ou factuelle
      • Réorganisation de l’article
      • Correction des erreurs factuelles
      • Ajout de nouvelles informations
    • Ne modifiez pas la date si la mise à jour est insignifiante
      • Correction des fautes de frappe et de la mise en forme
  • title: chaîne unique de 43 à 59 caractères longs (y compris les espaces)
    • N’incluez pas d’identificateur de site (généré automatiquement)
    • Cas de phrase - mettre en majuscule uniquement le premier mot et tous les noms appropriés
  • description: 115-145 caractères, y compris les espaces - ce résumé s’affiche dans le résultat de la recherche

Mise en forme

  • Éléments de syntaxe Backtick qui apparaissent, inline, dans un paragraphe
    • Noms d’applets de commande Verb-Noun
    • Variable $counter
    • Exemples syntactiques Verb-Noun -Parameter
    • Chemins d’accès aux fichiers C:\Program Files\PowerShell, /usr/bin/pwsh
    • URL qui ne sont pas destinées à être cliquables dans le document
    • Valeurs de propriété ou de paramètre
  • Utilisez en gras pour les noms de propriétés, les noms de paramètres, les noms de classes, les noms de module, les noms d’entités, les objets ou les noms de types
    • La mise en gras est utilisée pour le balisage sémantique, et non pour l’accentuation.
    • Gras : utiliser des astérisques **
  • Italique - utiliser un trait de soulignement _
    • Utilisé uniquement pour l’accentuation, et non pour le balisage sémantique
  • Sauts de ligne à 100 colonnes (ou à 80 pour about_Topics)
  • Aucun onglet dur : utiliser des espaces uniquement
  • Aucun espace de fin sur les lignes
  • Les mots clés et opérateurs PowerShell doivent être tous en minuscules
  • Utilisez la casse appropriée (Pascal) pour les noms et les paramètres des applets de commande.

headers

  • Commencer par H1 en premier - un seul H1 par article
  • Utiliser les en-têtes ATX uniquement
  • Utiliser une majuscule seulement pour la première lettre de tous les en-têtes
  • Ne sautez pas les niveaux - aucun H3 sans H2
  • Limiter la profondeur d’en-tête à H3 ou H4
  • Ajouter des lignes vides avant et après
  • Ne pas ajouter ou supprimer d’en-têtes - PlatyPS applique des en-têtes spécifiques dans son schéma

Blocs de code

  • Ajouter des lignes vides avant et après
  • Utiliser des clôtures de code étiquetées - PowerShell, Sortie ou autre ID de langage approprié
  • Utiliser une clôture de code non marquée pour les blocs de syntaxe
  • Placez la sortie dans un bloc de code distinct, à l’exception d’exemples de base où vous n’avez pas l’intention pour le lecteur d’utiliser le bouton Copier
  • Voir la liste des langues prises en charge

Listes

  • Indentez correctement
  • Ajouter des lignes vides avant le premier élément et après le dernier élément
  • Utiliser le trait d’union (-) pour les puces qui ne sont pas astérisques (*) pour réduire la confusion avec accentuation
  • Utiliser 1. pour tous les éléments d’une liste numérotée

Terminologie

Exemples de référence de cmdlet

  • Doit contenir au moins un exemple dans la référence cmdlet.

  • Les exemples ne doivent être que suffisamment de code pour illustrer l’utilisation

  • Syntaxe PowerShell

    • Utiliser des noms complets d’applets de commande et de paramètres - aucun alias
    • Utiliser "splatting" pour les paramètres lorsque la ligne de commande est trop longue
    • Évitez d’utiliser des backticks pour la continuation de ligne - utilisez uniquement si nécessaire

  • Supprimez ou simplifiez l’invite PowerShell (PS>) sauf si nécessaire pour l’exemple

  • L’exemple de référence de cmdlet doit suivre le schéma PlatyPS

    ### Example 1 - Descriptive title

Zero or more short descriptive paragraphs explaining the context of the example followed by one or
more code blocks. Recommend at least one and no more than two.

```powershell
... one or more PowerShell code statements ...
```

```Output
Example output of the code above.
```

Zero or more optional follow up paragraphs that explain the details of the code and output.

  • ne placez pas de paragraphes entre les blocs de code. Tout le contenu descriptif doit se présenter avant ou après les blocs de code.

Liaison à d’autres documents

  • Lors de la liaison en dehors du jeu de documents ou entre la référence d’applet de commande et le contenu conceptuel
    • Utiliser des URL relatives au site lors de la liaison à Microsoft Learn (supprimer https://learn.microsoft.com/en-us)
    • n'incluez pas les paramètres régionaux dans les URL des propriétés Microsoft (enlevez /en-us de l'URL)
    • Toutes les URL vers des sites web externes doivent utiliser HTTPS, sauf s’il n’est pas valide pour le site cible
  • Lorsqu'on établit des liens dans l'ensemble de documents
    • Utiliser le chemin de fichier relatif (../folder/file.md)
  • Tous les chemins utilisent des caractères de barre oblique (/)
  • Les liens d’image doivent avoir un texte alternatif unique