Udostępnij za pośrednictwem

Lista kontrolna redaktora

Ten artykuł zawiera podsumowaną listę reguł pisania lub edytowania dokumentacji programu PowerShell. Zobacz inne artykuły w przewodniku współautora, aby uzyskać szczegółowe wyjaśnienia i przykłady tych reguł.

Metadane

  • ms.date: musi mieć format MM/DD/RRRR
    • Zmień datę, gdy istnieje znacząca lub rzeczowa aktualizacja
      • Reorganizacja artykułu
      • Naprawianie błędów faktycznych
      • Dodawanie nowych informacji
    • Nie zmieniaj daty, jeśli aktualizacja jest nieistotna
      • Naprawianie literówek i formatowania
  • title: unikatowy ciąg o długości od 43 do 59 znaków (w tym spacje)
    • Nie dołączaj identyfikatora witryny (jest on generowany automatycznie)
    • Używaj formatowania zdań — wielką literą tylko pierwsze słowo i dowolne właściwe rzeczowniki.
  • description: 115–145 znaków, w tym spacje — to streszczenie jest wyświetlane w wynikach wyszukiwania

Formatowanie

  • Elementy składni typu 'backtick', które pojawiają się inline w akapicie tekstu
    • Nazwy poleceń cmdlet Verb-Noun
    • Zmienna $counter
    • Przykłady składni Verb-Noun -Parameter
    • Ścieżki plików C:\Program Files\PowerShell, /usr/bin/pwsh
    • Adresy URL, które nie mają być klikalne w dokumencie
    • Wartości właściwości lub parametrów
  • Użyj pogrubienia nazw właściwości, nazw parametrów, nazw klas, nazw modułów, nazw jednostek, obiektów lub nazw typów
    • Pogrubienie jest używane do znaczników semantycznych, a nie do podkreślania znaczenia.
    • Pogrubienie — używanie gwiazdki **
  • Kursywa — użyj podkreślenia _
    • Używane tylko do wyróżnienia, a nie do semantycznego znakowania
  • Podziały wierszy na 100 kolumn (lub na 80 dla about_Topics)
  • Brak twardych tabulatorów — używaj tylko spacji
  • Brak spacji końcowych w wierszach
  • Słowa kluczowe i operatory programu PowerShell powinny mieć małe litery
  • Użyj odpowiedniego stylu pisania (Pascal) dla nazw poleceń cmdlet i parametrów

Nagłówki

  • Najpierw zacznij od H1 — tylko jeden H1 na artykuł
  • Używaj tylko nagłówków ATX
  • Używaj zdaniowej wielkości liter dla wszystkich nagłówków
  • Nie pomijaj poziomów — nie ma H3 bez H2
  • Ogranicz głębokość nagłówka do H3 lub H4
  • Dodaj puste wiersze przed i po
  • Nie dodawaj ani nie usuwaj nagłówków — platyPS wymusza określone nagłówki w schemacie

Bloki kodu

  • Dodaj puste wiersze przed i po
  • Używanie otagowanych ogrodzeń kodu — powershell, output lub innego odpowiedniego identyfikatora języka
  • Użyj nieoznaczonej ramki kodu do bloków składni
  • Umieść dane wyjściowe w osobnym bloku kodu z wyjątkiem podstawowych przykładów, w których nie zamierzasz używać przycisku Kopiuj dla czytelnika
  • Zobacz listę obsługiwanych języków

Listach

  • Prawidłowe wcięcie
  • Dodaj puste wiersze przed pierwszym elementem i po ostatnim elemencie
  • Użyj łącznika (-) zamiast gwiazdki (*) do oznaczania punktorów, aby uniknąć zamieszania z akcentowaniem.
  • Użyj 1. dla wszystkich elementów na liście numerowanej

Terminologia

Przykłady odnośników do cmdletów

  • Musi zawierać co najmniej jeden przykład w odniesieniu polecenia cmdlet

  • Przykłady powinny zawierać tylko tyle kodu, aby zademonstrować użycie.

  • Składnia środowiska PowerShell

    • Używanie pełnych nazw poleceń cmdlet i parametrów — brak aliasów
    • Użyj splattingu dla parametrów, gdy wiersz polecenia jest zbyt długi
    • Unikaj używania apostrofów odwrotnych do kontynuacji linii — należy używać tylko wtedy, gdy jest to konieczne

  • Usuń lub uprość wiersz polecenia programu PowerShell (PS>), z wyjątkiem przypadków, w których jest to wymagane dla przykładu

  • Przykład odniesienia do poleceń cmdlet musi być zgodny z następującym schematem 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.

  • nie umieszczaj akapitów między blokami kodu. Cała zawartość opisowa musi znajdować się przed blokami kodu lub po nim.

Łączenie z innymi dokumentami

  • Podczas łączenia poza zestawem dokumentacji lub między referencjami do poleceń cmdlet a dokumentacją koncepcyjną
    • Użyj adresów URL względnych witryny do łączenia z usługą Microsoft Learn (usuń https://learn.microsoft.com/en-us)
    • nie dołączaj ustawień regionalnych do adresów URL w zasobach Microsoft (usuń /en-us z adresu URL)
    • Wszystkie adresy URL zewnętrznych witryn internetowych powinny używać protokołu HTTPS, chyba że jest to nieprawidłowe dla witryny docelowej
  • Podczas łączenia w zestawie dokumentów
    • Użyj względnej ścieżki pliku (../folder/file.md)
  • Wszystkie ścieżki używają znaku ukośnika (/)
  • Łącza obrazów powinny mieć unikatowy tekst alternatywny