Udostępnij za pomocą

Pisanie pomocy dotyczącej poleceń cmdlet programu PowerShell

Polecenia cmdlet programu PowerShell mogą być przydatne, ale jeśli tematy Pomocy wyraźnie wyjaśnią, co robi polecenie cmdlet i jak go używać, polecenie cmdlet może nie być używane lub, co gorsza, może to spowodować sfrustrowanie użytkowników. Format pliku Pomocy opartego na kodzie XML zwiększa spójność, ale bardzo pomoc wymaga znacznie więcej.

Jeśli nigdy nie napisałeś pomocy dotyczącej poleceń cmdlet, zapoznaj się z poniższymi wskazówkami. Schemat XML wymagany do utworzenia tematu pomocy polecenia cmdlet został opisany w poniższej sekcji. Zacznij od Tworzenie pliku pomocy polecenia cmdlet. Ten temat zawiera opis węzłów XML najwyższego poziomu.

Pisanie wytycznych dotyczących pomocy dotyczącej poleceń cmdlet

Dobrze napisz

Nic nie zastępuje dobrze napisanego tematu. Jeśli nie jesteś profesjonalnym pisarzem, znajdź pisarza lub redaktora, aby ci pomóc. Inną alternatywą jest skopiowanie tekstu Pomocy do programu Microsoft Word i użycie sprawdzania gramatyki i pisowni w celu ulepszenia pracy.

Pisanie po prostu

Użyj prostych słów i fraz. Unikaj żargonu. Należy wziąć pod uwagę, że wielu czytelników jest wyposażonych tylko w słownik języka obcego i temat Pomocy.

Spójnie zapisuj

Pomoc dotycząca powiązanych poleceń cmdlet powinna być podobna (na przykład Get-Content i Set-Content). Użyj standardowych opisów standardowych parametrów, takich jak Force i InputObject. (Skopiuj je z Pomocy dla podstawowych poleceń cmdlet). Użyj standardowych terminów. Na przykład użyj polecenia "parameter", a nie "argument" i użyj polecenia "cmdlet", a nie "command" lub "command-let".

Rozpoczynanie synchronizacji z czasownikiem

Pole synopsis informuje użytkownika o tym, co robi polecenie cmdlet, a nie co to jest ani jak działa. Czasowniki tworzą instrukcję opartą na zadaniach, która informuje użytkowników, czy to polecenie cmdlet spełnia ich wymagania. Używaj prostych czasowników, takich jak "get", "create" i "change". Unikaj "set", które mogą być niejasne i fantazyjne słowa, takie jak "modify".

Koncentracja na obiektach

Większość poleceń cmdlet "get" wyświetla coś, ale ich podstawową funkcją jest pobranie obiektu. W Pomocy skoncentruj się na obiekcie, aby użytkownicy wiedzieli, że domyślny ekran jest jednym z wielu i że mogą używać metod i właściwości obiektu pobranego dla nich na różne sposoby.

Pisanie szczegółowych opisów

Krótko podaj listę wszystkich czynności, które można wykonać za pomocą polecenia cmdlet w szczegółowym opisie. Jeśli funkcja main ma zmienić jedną właściwość, ale polecenie cmdlet może zmienić wszystkie właściwości, wyświetl tę listę w szczegółowym opisie.

Używanie konwencjonalnej składni

Użyj standardowego formatu Backus-Naur, który jest typowy dla pomocy wiersza polecenia systemu Windows i Unix.

Używanie typów platformy Microsoft .NET dla wartości parametrów

Symbole zastępcze wartości parametrów (w składni i opisach parametrów) pokazują typy .NET Framework obiektów, które będą akceptowane przez parametr. Zespół programu PowerShell opracował tę konwencję, aby ułatwić nauczenie użytkowników programu .NET Framework.

Pisanie pełnych opisów parametrów

Opisy parametrów muszą informować użytkowników o dwóch rzeczach: co parametr robi (jego efekt) i co muszą wpisać dla wartości parametrów.

Pisanie praktycznych przykładów

Przykłady powinny pokazać, jak używać wszystkich parametrów, ale najważniejszą rzeczą jest pokazanie, jak używać polecenia cmdlet w rzeczywistych zadaniach. Zacznij od prostego przykładu i napisz coraz bardziej złożone przykłady. W ostatnim przykładzie pokazano, jak używać polecenia cmdlet w potoku.

Korzystanie z pola Notatki

Użyj pola Uwagi, aby wyjaśnić pojęcia, które użytkownicy muszą zrozumieć polecenie cmdlet. Możesz również użyć notatek, aby pomóc użytkownikom uniknąć typowych błędów. Unikaj adresów URL w miarę ich zmieniania. Zamiast tego podaj terminy użytkowników do wyszukania.

Testowanie pomocy

Przetestuj pomoc tak samo, jak testujesz kod. Udostępnij znajomym i współpracownikom swoją zawartość Pomocy i prześlij opinię. Możesz również poprosić o opinię ze strony grup dyskusyjnych.

Zobacz też

  • Last updated on