Bagikan melalui

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
  • Last updated on