Bagikan melalui

Menulis Bantuan untuk Cmdlet PowerShell

Cmdlet PowerShell dapat berguna, tetapi kecuali topik Bantuan Anda menjelaskan dengan jelas apa yang dilakukan cmdlet dan cara menggunakannya, cmdlet mungkin tidak digunakan atau, bahkan lebih buruk, itu mungkin membuat pengguna frustrasi. Format file Bantuan cmdlet berbasis XML meningkatkan konsistensi, tetapi bantuan besar membutuhkan lebih banyak lagi.

Jika Anda belum pernah menulis Bantuan cmdlet, tinjau panduan berikut. Skema XML yang diperlukan untuk menulis topik Bantuan cmdlet dijelaskan di bagian berikut. Mulailah dengan Membuat File Bantuan Cmdlet. Topik tersebut menyertakan deskripsi simpul XML tingkat atas.

Panduan Penulisan untuk Bantuan Cmdlet

Menulis dengan baik

Tidak ada yang menggantikan topik yang ditulis dengan baik. Jika Anda bukan penulis profesional, temukan penulis atau editor untuk membantu Anda. Alternatif lainnya adalah menyalin teks Bantuan Anda ke Microsoft Word dan menggunakan pemeriksaan tata bahasa dan ejaan untuk meningkatkan pekerjaan Anda.

Tulis sederhana

Gunakan kata dan frasa sederhana. Hindari jargon. Pertimbangkan bahwa banyak pembaca hanya dilengkapi dengan kamus bahasa asing dan topik Bantuan Anda.

Menulis secara konsisten

Bantuan untuk cmdlet terkait harus serupa (misalnya, Get-Content dan Set-Content). Gunakan deskripsi standar untuk parameter standar, seperti Force dan InputObject. (Salin dari Bantuan untuk cmdlet inti.) Gunakan istilah standar. Misalnya, gunakan "parameter", bukan "argumen", dan gunakan "cmdlet" bukan "command" atau "command-let."

Memulai sinopsis dengan kata kerja

Bidang sinopsis memberi tahu pengguna apa yang dilakukan cmdlet, bukan apa itu atau cara kerjanya. Kata kerja membuat pernyataan berbasis tugas yang memberi tahu pengguna jika cmdlet ini memenuhi persyaratan mereka. Gunakan kata kerja sederhana seperti "get", "create", dan "change." Hindari "set", yang bisa samar dan kata-kata mewah seperti "modifikasi".

Fokus pada objek

Sebagian besar cmdlet "dapatkan" menampilkan sesuatu, tetapi fungsi utamanya adalah mendapatkan objek. Di Bantuan Anda, fokus pada objek , sehingga pengguna memahami bahwa tampilan default adalah salah satu dari banyak, dan bahwa mereka dapat menggunakan metode dan properti objek yang Anda ambil untuk mereka dengan cara yang berbeda.

Menulis deskripsi terperinci

Cantumkan secara singkat semua yang dapat dilakukan cmdlet dalam deskripsi terperinci. Jika fungsi utamanya adalah mengubah satu properti, tetapi cmdlet dapat mengubah semua properti, cantumkan ini dalam deskripsi terperinci.

Menggunakan sintaks konvensional

Gunakan format Backus-Naur standar yang umum untuk Bantuan baris perintah Windows dan Unix.

Gunakan jenis Microsoft .NET untuk nilai parameter

Tempat penampung untuk nilai parameter (dalam sintaks dan deskripsi parameter) menunjukkan jenis .NET Framework objek yang akan diterima parameter. Tim PowerShell mengembangkan konvensi ini untuk membantu mengajarkan pengguna tentang .NET Framework.

Menulis deskripsi parameter lengkap

Deskripsi parameter harus memberi tahu pengguna tentang dua hal: apa yang dilakukan parameter (efeknya) dan apa yang harus mereka ketik untuk nilai parameter.

Menulis contoh praktis

Contohnya harus menunjukkan cara menggunakan semua parameter, tetapi yang paling penting adalah menunjukkan cara menggunakan cmdlet dalam tugas dunia nyata. Mulailah dengan contoh sederhana dan tulis contoh yang semakin kompleks. Dalam contoh akhir, tunjukkan cara menggunakan cmdlet dalam alur.

Menggunakan bidang Catatan

Gunakan bidang Catatan untuk menjelaskan konsep yang perlu dipahami pengguna cmdlet. Anda juga dapat menggunakan catatan untuk membantu pengguna menghindari kesalahan umum. Hindari URL saat berubah. Sebagai gantinya, berikan istilah pengguna untuk dicari.

Menguji Bantuan Anda

Uji Bantuan seperti Anda menguji kode Anda. Minta teman dan kolega membaca konten Bantuan Anda dan berikan umpan balik. Anda juga dapat mendapatkan umpan balik dari grup-berita.

Lihat Juga