Menulis Bantuan untuk Skrip dan Fungsi PowerShell

Skrip dan fungsi PowerShell harus sepenuhnya didokumenkan setiap kali dibagikan dengan orang lain. Cmdlet Get-Help menampilkan skrip dan topik bantuan fungsi dalam format yang sama karena menampilkan bantuan untuk cmdlet, dan semua parameter Get-Help bekerja pada topik bantuan skrip dan fungsi.

Skrip PowerShell dapat menyertakan topik bantuan tentang skrip dan topik bantuan tentang setiap fungsi dalam skrip. Fungsi yang dibagikan secara independen dari skrip dapat menyertakan topik bantuan mereka sendiri.

Dokumen ini menjelaskan format dan penempatan topik bantuan yang benar, dan menyarankan panduan untuk konten.

Jenis Bantuan Skrip dan Fungsi

Bantuan Comment-Based

Topik bantuan yang menjelaskan skrip atau fungsi dapat diimplementasikan sebagai serangkaian komentar dalam skrip atau fungsi. Saat menulis bantuan berbasis komentar untuk skrip dan untuk fungsi dalam skrip, perhatikan dengan cermat aturan untuk menempatkan bantuan berbasis komentar. Penempatan menentukan apakah cmdlet Get-Help mengaitkan topik bantuan dengan skrip atau fungsi. Untuk informasi selengkapnya tentang menulis topik bantuan berbasis komentar, lihat about_Comment_Based_Help.

Bantuan Perintah XML-Based

Topik bantuan yang menjelaskan skrip atau fungsi dapat diimplementasikan dalam file XML yang menggunakan skema bantuan perintah. Untuk mengaitkan skrip atau fungsi dengan file XML, gunakan kata kunci komentar .EXTERNALHELP diikuti dengan jalur dan nama file XML.

Ketika kata kunci komentar .EXTERNALHELP ada, itu lebih diutamakan daripada bantuan berbasis komentar, bahkan ketika Get-Help tidak dapat menemukan file bantuan yang cocok dengan nilai kata kunci .EXTERNALHELP.

Bantuan Online

Anda dapat memposting topik bantuan Anda di internet dan kemudian mengarahkan Get-Help untuk membuka topik. Untuk informasi selengkapnya tentang menulis topik bantuan berbasis komentar, lihat Bantuan Online Pendukung.

Tidak ada metode yang ditetapkan untuk menulis topik konseptual ("Tentang") untuk skrip dan fungsi. Namun, Anda dapat memposting topik konseptual di internet mencantumkan topik dan URL-nya di bagian Tautan Terkait dari topik bantuan perintah.

Pertimbangan Konten untuk Bantuan Skrip dan Fungsi

• Jika Anda menulis topik bantuan yang sangat singkat hanya dengan beberapa bagian bantuan perintah yang tersedia, pastikan untuk menyertakan deskripsi yang jelas tentang parameter skrip atau fungsi. Sertakan juga satu atau dua contoh perintah di bagian contoh, bahkan jika Anda memutuskan untuk menghilangkan deskripsi contoh.

• Dalam semua deskripsi, lihat perintah sebagai skrip atau fungsi. Informasi ini membantu pengguna memahami dan mengelola perintah.

  Misalnya, deskripsi terperinci berikut menyatakan bahwa perintah New-Topic adalah skrip. Ini mengingatkan pengguna bahwa mereka perlu menentukan jalur dan nama lengkap saat menjalankannya.

  "Skrip New-Topic membuat topik konseptual kosong untuk setiap nama topik dalam file input..."

  Deskripsi terperinci berikut menyatakan bahwa Disable-PSRemoting adalah fungsi. Informasi ini sangat berguna bagi pengguna ketika sesi menyertakan beberapa perintah dengan nama yang sama, beberapa di antaranya mungkin disembunyikan oleh perintah dengan prioritas yang lebih tinggi.

  Fungsi Disable-PSRemoting menonaktifkan semua konfigurasi sesi pada komputer lokal...

• Dalam topik bantuan skrip, jelaskan cara menggunakan skrip secara keseluruhan. Jika Anda juga menulis topik bantuan untuk fungsi dalam skrip, sebutkan fungsi dalam topik bantuan skrip Anda dan sertakan referensi ke topik bantuan fungsi di bagian Tautan Terkait dari topik bantuan skrip. Sebaliknya, ketika fungsi adalah bagian dari skrip, jelaskan dalam topik bantuan fungsi peran yang dimainkan fungsi dalam skrip dan bagaimana fungsi tersebut dapat digunakan secara independen. Kemudian cantumkan topik bantuan skrip di bagian Tautan Terkait dari topik bantuan fungsi.

• Saat menulis contoh untuk topik bantuan skrip, pastikan untuk menyertakan jalur ke file skrip dalam perintah contoh. Ini mengingatkan pengguna bahwa mereka harus menentukan jalur secara eksplisit, bahkan ketika skrip berada di direktori saat ini.

• Dalam topik bantuan fungsi, ingatkan pengguna bahwa fungsi hanya ada di sesi saat ini dan, untuk menggunakannya di sesi lain, mereka perlu menambahkannya, atau menambahkannya ke profil PowerShell.

• Get-Help menampilkan topik bantuan untuk skrip atau fungsi hanya ketika file skrip dan file topik bantuan disimpan di lokasi yang benar. Oleh karena itu, tidak berguna untuk menyertakan instruksi untuk menginstal PowerShell, atau menyimpan atau menginstal skrip atau fungsi dalam topik bantuan skrip atau fungsi. Sebagai gantinya, sertakan instruksi penginstalan apa pun dalam dokumen yang Anda gunakan untuk mendistribusikan skrip atau fungsi.

Lihat Juga

Menulis Comment-Based Topik Bantuan