Udostępnij za pośrednictwem

Wnoszenie poprawy jakości

Nie musisz być ekspertem lub ekspertem w zakresie dokumentacji, aby współtworzyć. Jeśli zobaczysz możliwość ulepszenia dokumentacji, wyślij pull request z proponowanym ulepszeniem. W tym przewodniku opisano kilka prostych sposobów, w jaki każda osoba może przyczynić się do ulepszeń jakości w dokumentacji.

Skupiamy się na tych obszarach jakości:

Formatowanie przykładów kodu

Wszystkie przykłady kodu powinny być zgodne z wytycznymi dotyczącymi stylu zawartości programu PowerShell. Te reguły są powtarzane w skróconej postaci dla wygody:

  • Wszystkie bloki kodu powinny być zawarte w potrójnej sekwencji backticków (```).
  • Długość wiersza w blokach kodu jest ograniczona do 90 znaków w artykułach referencyjnych dla poleceń cmdlet.
  • Długość wiersza bloków kodu jest ograniczona do 76 znaków w artykułach about_*.
  • Unikaj używania znaków kontynuacji wiersza (`) w przykładach kodu programu PowerShell.
    • Użyj możliwości rozplatania lub naturalnego podziału wiersza, takich jak znaki kreski kreskowej (|), otwierając nawiasy klamrowe (), nawiasy (}() i nawiasy ([), aby ograniczyć długość linii.
  • Dołącz tylko monit programu PowerShell do ilustracyjnych przykładów, w których kod nie jest przeznaczony do wklejania kopii.
  • Nie używaj aliasów w przykładach, chyba że dokumentujesz alias.
  • Unikaj używania parametrów pozycyjnych. Użyj nazwy parametru, nawet jeśli parametr jest pozycyjny.

Składnia polecenia formatowania

Wszystkie teksty powinny być zgodne z wytycznymi dotyczącymi stylu dla zawartości PowerShell. Te reguły są powtarzane tutaj dla wygody:

  • Zawsze używaj pełnej nazwy cmdletów i parametrów. Unikaj używania aliasów, chyba że robisz to celowo w celu demonstracji.
  • Właściwość, parametr, obiekt, nazwy typów, nazwy klas, metody klas powinny być pogrubione.
    • Wartości właściwości i parametrów powinny być opakowane w backticks (`).
    • W przypadku odwoływania się do typów przy użyciu stylu nawiasów, używaj znaków `backtick`. Na przykład: [System.Io.FileInfo]
  • Nazwy modułów programu PowerShell powinny być pogrubione.
  • Słowa kluczowe i operatory programu PowerShell powinny mieć małe litery.
  • Użyj odpowiedniej wielkości liter (Pascal) dla nazw i parametrów poleceń cmdlet.
  • Jeśli odwołujesz się do parametru według nazwy, nazwa powinna być pogrubiona.
  • Użyj nazwy parametru z łącznikiem, jeśli ilustrujesz składnię. Owiń parametr w apostrofy tylne.
  • Gdy pokazujesz przykładowe użycie polecenia zewnętrznego, przykład powinien być ujęty w znaki backtick. Zawsze dołączaj rozszerzenie pliku polecenia zewnętrznego.

Aby zapewnić łatwość konserwacji i czytelność źródła języka Markdown dla naszej dokumentacji, konwertujemy naszą dokumentację koncepcyjną, aby używać odwołań do linków zamiast linków wbudowanych.

Na przykład zamiast:

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

Powinien to być:

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

Uwaga

Po zastąpieniu linku wbudowanego dostosuj zawartość, aby zmieścić się w 100 znakach. Możesz użyć rozszerzenia VS Code reflow-markdown , aby szybko przepełnić akapit.

W dolnej części pliku dodaj komentarz markdown przed definicją linków.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Upewnij się, że:

  1. Każde łącze wskazuje poprawną lokalizację.
  2. Nie duplikuj definicji odwołań linków. Jeśli definicja odwołania do linku już istnieje dla adresu URL, użyj ponownie istniejącego odwołania zamiast utworzyć nowe.
  3. Definicje odnośników znajdują się w dolnej części pliku po komentarzu markdown i są w kolejności liczbowej.

Linting Markdownu

W przypadku dowolnego artykułu w jednym z uczestniczących repozytoriów otwarcie artykułu w programie VS Code powoduje wyświetlenie ostrzeżeń dotyczących lintingu. Rozwiąż dowolne z tych ostrzeżeń, z wyjątkiem:

  • MD022/blanks-around-headings/blanks-around-headers dla nagłówka Synopsis w dokumentach referencyjnych cmdlet. W przypadku tych elementów naruszenie reguły jest zamierzone, aby zapewnić prawidłowe kompilowanie dokumentacji przy użyciu platformy PlatyPS.

Upewnij się, czy długości linii są poprawne, i użyj rozszerzenia Reflow Markdown, aby poprawić wszelkie długie wiersze.

Ortografia

Pomimo naszych najlepszych wysiłków, literówki i błędy ortograficzne przedostają się do dokumentacji. Te błędy utrudniają śledzenie i lokalizowanie dokumentacji. Naprawienie tych błędów sprawia, że dokumentacja jest bardziej czytelna, zwłaszcza w przypadku osób nie mówiących po angielsku, które polegają na dokładnych tłumaczeniach.

  • Last updated on