Bagikan melalui

Berkontribusi peningkatan kualitas

Anda tidak harus menjadi pakar subjek atau ahli dokumentasi untuk berkontribusi. Jika Anda melihat kesempatan untuk meningkatkan dokumentasi, kirimkan permintaan pull dengan peningkatan yang Anda usulkan. Panduan ini menguraikan beberapa cara sederhana agar siapa pun dapat berkontribusi pada peningkatan kualitas pada dokumentasi.

Kami berfokus pada area kualitas ini:

Sampel kode pemformatan

Semua sampel kode harus mengikuti panduan gaya untuk konten PowerShell. Aturan tersebut diulang dalam bentuk singkatan di sini untuk kenyamanan:

  • Semua blok kode harus dimuat dalam pagar kode triple-backtick (```).
  • Panjang baris untuk blok kode terbatas pada 90 karakter untuk artikel referensi cmdlet.
  • Panjang baris untuk blok kode terbatas pada 76 karakter untuk about_* artikel.
  • Hindari menggunakan karakter kelanjutan baris (`) dalam contoh kode PowerShell.
    • Gunakan peluang percikan atau pemutusan garis alami, seperti setelah karakter pipa (|), kurung kurung (}), tanda kurung ((), dan tanda kurung ([) untuk membatasi panjang garis.
  • Hanya sertakan perintah PowerShell untuk contoh ilustrasi di mana kode tidak ditujukan untuk penyalinan.
  • Kecuali jika Anda secara khusus mendokumentasikan alias, jangan gunakan alias dalam contoh.
  • Hindari menggunakan parameter posisi. Gunakan nama parameter, bahkan jika parameter berposisi.

Sintaks perintah pemformatan

Semua prosa harus mengikuti panduan gaya untuk konten PowerShell. Aturan tersebut diulang di sini untuk kenyamanan:

  • Selalu gunakan nama lengkap untuk cmdlet dan parameter. Hindari menggunakan alias kecuali Anda secara khusus menunjukkan alias.
  • Properti, parameter, objek, nama jenis, nama kelas, metode kelas harus ditebalkan.
    • Nilai properti dan parameter harus dibungkus dalam tanda backtick (```).
    • Saat merujuk ke tipe menggunakan gaya kurung siku, gunakan tanda backtick. Misalnya: [System.Io.FileInfo]
  • Nama modul PowerShell harus tebal.
  • Kata kunci dan operator PowerShell harus semua huruf kecil.
  • Gunakan casing yang tepat (Pascal) untuk nama cmdlet dan parameter.
  • Saat Anda merujuk ke parameter berdasarkan nama, nama harus ditebalkan.
  • Gunakan nama parameter dengan tanda hubung jika Anda mengilustrasikan sintaks. Bungkus parameter dalam backtick.
  • Saat Anda menampilkan contoh penggunaan perintah eksternal, contohnya harus dibungkus dalam backtick. Selalu sertakan ekstensi file untuk perintah eksternal.

Untuk pemeliharaan dan keterbacaan sumber markdown untuk dokumentasi kami, kami mengonversi dokumentasi konseptual kami untuk menggunakan referensi tautan alih-alih tautan sebaris.

Misalnya, sebagai ganti dari:

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

Seharusnya:

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

Nota

Saat Anda mengganti tautan sebaris, sesuaikan konten agar dibatasi pada 100 karakter. Anda dapat menggunakan ekstensi reflow-markdown VS Code untuk mengalirkan ulang paragraf dengan cepat.

Di bagian bawah file, tambahkan komentar markdown sebelum definisi tautan.

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

Pastikan bahwa:

  1. Setiap tautan menunjuk ke lokasi yang benar.
  2. Jangan menduplikasi definisi referensi tautan. Jika definisi referensi tautan sudah ada untuk URL, gunakan kembali referensi yang ada alih-alih membuat yang baru.
  3. Definisi referensi tautan berada di bagian bawah file setelah komentar markdown dan berada dalam urutan numerik.

Markdown linting

Untuk artikel apa pun di salah satu repositori peserta, membuka artikel di VS Code menampilkan peringatan linting. Atasi salah satu peringatan ini yang Anda temukan, kecuali:

Pastikan panjang garis dan gunakan ekstensi Markdown Reflow untuk memperbaiki garis panjang apa pun.

Ejaan

Meskipun sudah berusaha sebaik mungkin, kesalahan ketik dan ejaan tetap terjadi dan masuk ke dalam dokumentasi. Kesalahan ini membuat dokumentasi lebih sulit diikuti dan dilokalkan. Memperbaiki kesalahan ini membuat dokumentasi lebih mudah dibaca, terutama untuk penutur non-bahasa Inggris yang mengandalkan terjemahan yang akurat.

  • Last updated on