Daftar periksa editor

Artikel ini berisi daftar ringkasan aturan untuk menulis atau mengedit dokumentasi PowerShell. Lihat artikel lain di Panduan Kontributor untuk penjelasan terperinci dan contoh aturan ini.

Metainformasi

  • ms.date: harus dalam format MM/DD/YYYY
    • Mengubah tanggal saat ada pembaruan yang signifikan atau faktual
      • Mengatur ulang artikel
      • Memperbaiki kesalahan faktual
      • Menambahkan informasi baru
    • Jangan ubah tanggal jika pembaruan tidak signifikan
      • Memperbaiki kesalahan ketik dan pemformatan
  • title: string unik sepanjang 43-59 karakter (termasuk spasi)
    • Jangan sertakan pengidentifikasi situs (dibuat secara otomatis)
    • Gunakan kapitalisasi kalimat - hanya kapitalisasi kata pertama dan kata benda yang tepat
  • description: 115-145 karakter termasuk spasi - abstrak ini ditampilkan dalam hasil pencarian

Pemformatan

  • Elemen sintaks backtick yang muncul, sebaris, dalam paragraf
    • Nama cmdlet Verb-Noun
    • Variabel $counter
    • Contoh sintaksis Verb-Noun -Parameter
    • Jalur file C:\Program Files\PowerShell, /usr/bin/pwsh
    • URL yang tidak dimaksudkan untuk dapat diklik dalam dokumen
    • Nilai properti atau parameter
  • Gunakan tebal untuk nama properti, nama parameter, nama kelas, nama modul, nama entitas, objek, atau nama jenis
    • Tebal digunakan untuk markup semantik, bukan penekanan
    • Tebal - gunakan tanda bintang **
  • Tulisan miring - gunakan garis bawah _
    • Hanya digunakan untuk penekanan, bukan untuk markup semantik
  • Pemisah baris pada 100 kolom (atau di 80 untuk about_Topics)
  • Tidak ada tab keras - gunakan spasi saja
  • Tidak ada spasi akhir di baris
  • Kata kunci dan operator PowerShell harus semua huruf kecil
  • Gunakan casing yang tepat (Pascal) untuk nama cmdlet dan parameter

Header

  • Mulai dengan H1 terlebih dahulu - hanya satu H1 per artikel
  • Gunakan Header ATX saja
  • Gunakan huruf besar pada awal kalimat untuk semua judul
  • Jangan lompat urutan - tidak boleh ada H3 tanpa H2
  • Batasi kedalaman header ke H3 atau H4
  • Menambahkan baris kosong sebelum dan sesudah
  • Jangan menambahkan atau menghapus header - PlatyPS memberlakukan header tertentu dalam skemanya

Blok kode

  • Menambahkan baris kosong sebelum dan sesudah
  • Gunakan pagar kode bertag - powershell, Output, atau ID bahasa lain yang sesuai
  • Menggunakan pagar kode yang tidak diberi tag untuk blok sintaksis
  • Letakkan output dalam blok kode terpisah kecuali untuk contoh dasar di mana Anda tidak berniat bagi pembaca untuk menggunakan tombol Salin
  • Lihat daftar bahasa yang didukung

Daftar

  • Inden dengan benar
  • Tambahkan baris kosong sebelum item pertama dan setelah item terakhir
  • Gunakan tanda hubung (-), bukan tanda bintang (*), untuk mengurangi kebingungan dengan penekanan.
  • Gunakan 1. untuk semua item dalam daftar bernomor

Terminologi

Contoh referensi cmdlet

  • Harus memiliki setidaknya satu contoh dalam referensi cmdlet

  • Contoh harus cukup kode saja untuk menunjukkan penggunaan

  • Sintaks PowerShell

    • Gunakan nama lengkap cmdlet dan parameter - tanpa alias
    • Gunakan splatting untuk parameter saat baris perintah terlalu panjang
    • Hindari menggunakan backtick untuk melanjutkan baris - gunakan hanya jika diperlukan

  • Menghapus atau menyederhanakan perintah PowerShell (PS>) kecuali jika diperlukan untuk contoh

  • Contoh referensi cmdlet harus mengikuti skema PlatyPS berikut

    ### Example 1 - Descriptive title

Zero or more short descriptive paragraphs explaining the context of the example followed by one or
more code blocks. Recommend at least one and no more than two.

```powershell
... one or more PowerShell code statements ...
```

```Output
Example output of the code above.
```

Zero or more optional follow up paragraphs that explain the details of the code and output.

  • jangan letakkan paragraf di antara blok kode. Semua konten deskriptif harus diletakkan sebelum atau sesudah blok kode.

Menautkan ke dokumen lain

  • Saat menautkan di luar docset atau antara referensi cmdlet dan konseptual
    • Gunakan URL relatif situs saat menautkan ke Microsoft Learn (hapus https://learn.microsoft.com/en-us)
    • jangan sertakan lokal dalam URL di properti Microsoft (hapus /en-us dari URL)
    • Semua URL ke situs web eksternal harus menggunakan HTTPS kecuali tidak valid untuk situs target
  • Saat menautkan di dalam docset
    • Gunakan jalur file relatif (../folder/file.md)
  • Semua jalur menggunakan karakter garis miring ke depan (/)
  • Tautan gambar harus memiliki teks alt yang unik
  • Terakhir diperbarui pada