Bagikan melalui

Berkontribusi peningkatan kualitas

Untuk Hacktoberfest 2022, kami menguji coba proses untuk memberikan kontribusi peningkatan kualitas pada konten PowerShell. Panduan ini menggeneralisasi proses tersebut untuk menentukan cara gesekan rendah bagi anggota komunitas untuk meningkatkan kualitas dokumentasi.

Kami berfokus pada area kualitas ini:

Pelacakan Proyek

Kami melacak kontribusi dengan Proyek GitHub PowerShell Docs Quality Contributions.

Halaman proyek memiliki beberapa tampilan untuk masalah dan PR yang terkait dengan upaya 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][31] displays all available
packages in the PowerShell Gallery.

Seharusnya:

The [Packages tab][31] 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. Tautan didefinisikan dalam urutan muncul dalam dokumen.
  2. Setiap tautan menunjuk ke lokasi yang benar.
  3. Definisi referensi tautan berada di bagian bawah file setelah komentar markdown dan berada dalam urutan yang benar.

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.

Proses

Kami mendorong Anda untuk memilih satu atau beberapa area kualitas dan artikel (atau grup artikel) untuk meningkatkan kualitasnya. Gunakan langkah-langkah berikut untuk memandu pekerjaan Anda:

  1. Periksa proyek untuk masalah yang diajukan terkait upaya ini agar tidak terjadi duplikasi upaya.

  2. Buka masalah baru di repositori yang sesuai:

  3. Ikuti panduan kontributor kami untuk menyiapkan perubahan Anda.

  4. Kirim permintaan penarikan Anda. Memastikan:

    1. Judul PR Anda memiliki awalan Quality: .

    2. Isi PR Anda mereferensikan masalah yang diselesaikannya sebagai item daftar yang tidak diurutkan dan menggunakan salah satu kata kunci penautan.

      Misalnya, jika Anda sedang mengerjakan masalah 123, isi PR Anda harus menyertakan Markdown berikut:

      - resolves #123

    Setelah Anda mengirimkan PR, para pemelihara akan meninjau pekerjaan Anda dan bekerja sama dengan Anda untuk menggabungkan PR tersebut.