Aracılığıyla paylaş

Düzenleyicinin denetim listesi

Bu makale, PowerShell belgelerini yazmaya veya düzenlemeye yönelik kuralların özetlenmiş bir listesini içerir. Bu kuralların ayrıntılı açıklamaları ve örnekleri için Katkıda Bulunan Kılavuzu'ndaki diğer makalelere bakın.

Meta veriler

  • ms.date: AA/GG/YYYYY biçiminde olmalıdır
    • Önemli veya olgusal bir güncelleştirmenin olduğu tarihi değiştirme
      • Makaleyi yeniden düzenleme
      • Olgusal hataları düzeltme
      • Yeni bilgi ekleme
    • Güncelleştirme önemsizse tarihi değiştirmeyin
      • Yazım hatalarını ve biçimlendirmeyi düzeltme
  • title: 43-59 karakter uzunluğunda benzersiz dize (boşluklar dahil)
    • Site tanımlayıcısı eklemeyin (otomatik olarak oluşturulur)
    • Cümle içi büyük harf kullanımı - yalnızca ilk sözcüğü ve uygun adları büyük harfle yaz
  • description: Boşluklar dahil 115-145 karakter - bu özet arama sonucunda görüntülenir

Biçimlendirme

  • Paragraf içinde satır içi olarak görünen arka uç söz dizimi öğeleri
    • Cmdlet adları Verb-Noun
    • Değişken $counter
    • Sentaktik örnekler Verb-Noun -Parameter
    • Dosya yolları C:\Program Files\PowerShell, /usr/bin/pwsh
    • Belgede tıklanabilir olması amaçlanmayan URL'ler
    • Özellik veya parametre değerleri
  • Özellik adları, parametre adları, sınıf adları, modül adları, varlık adları, nesne veya tür adları için kalın kullanın
    • Kalın, vurgulama için değil anlamsal işaretleme için kullanılır
    • Kalın - yıldız işareti kullan **
  • italik - alt çizgi kullan _
    • Yalnızca vurgu için kullanılır, anlamsal işaretleme için kullanılmaz
  • Satır sonları 100 sütunda (veya about_Topics için 80'de)
  • Sabit sekme yok - yalnızca boşluk kullanın
  • Satırlarda sonda boşluk yok
  • PowerShell anahtar sözcüklerinin ve işleçlerinin tümü küçük harf olmalıdır
  • Cmdlet adları ve parametreleri için uygun (Pascal) büyük/küçük harf kullanma

Başlıklar

  • önce H1 ile başlayın - makale başına yalnızca bir H1
  • Yalnızca ATX Üst Bilgilerini kullanma
  • Tüm başlıklar için cümle büyük/küçük harf kullanın
  • Düzeyleri atlamayın - H2 olmadan H3 yok
  • Başlık derinliğini sadece H3 veya H4 ile sınırla
  • Önce ve sonra boş satırlar ekleme
  • Başlık eklemeyin veya kaldırmayın - PlatyPS, şemasında belirli başlıkları zorunlu kılar.

Kod blokları

  • Önce ve sonra boş satırlar ekleme
  • Etiketli kod çitlerini kullanma - powershell, Output veya diğer uygun dil kimliği
  • Söz dizimi blokları için etiketsiz kod çiti kullanma
  • Okuyucunun Kopyala düğmesini kullanmasını istemediğiniz temel örnekler dışında çıkışı ayrı bir kod bloğuna yerleştirin
  • Desteklenen dillerin listesine bakın

Liste

  • Düzgün girintile
  • İlk öğeden önce ve son öğeden sonra boş satırlar ekleme
  • Vurguyla karışıklığı azaltmak için yıldız işareti (-) yerine tire (*) kullanın.
  • Numaralandırılmış listedeki tüm öğeler için kullanma 1.

Terminoloji

Cmdlet referans örnekleri

  • Cmdlet referansında en az bir örnek bulunmalıdır.

  • Örnekler yalnızca kullanımı göstermek için yeterli kod olmalıdır

  • PowerShell söz dizimi

    • Cmdlet'lerin ve parametrelerin tam adlarını kullanma - diğer ad yok
    • Komut satırı çok uzun olduğunda parametreler için splatting'i kullan
    • Satır devamlılığı ters tırnak işaretlerini kullanmaktan kaçının - yalnızca gerektiğinde kullanın

  • Örnek için gerekli durumlar dışında PowerShell istemini (PS>) kaldırın veya basitleştirin

  • Cmdlet başvuru örneği aşağıdaki PlatyPS şemasını izlemelidir

    ### 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.

  • paragrafları kod bloklarının arasına koymayın. Tüm açıklayıcı içerik kod bloklarının önüne veya arkasına gelmelidir.

Diğer belgelere bağlanma

  • Docset dışında veya cmdlet referansı ile kavramsal içerik arasında bağlantı oluştururken
    • Microsoft Learn'e bağlanırken site göreli URL'leri kullanın (remove https://learn.microsoft.com/en-us)
    • Microsoft özelliklerindeki URL'lerde yerel ayarları dahil etmeyin (URL'den /en-us kaldırın)
    • Dış web sitelerine yönelik tüm URL'ler, hedef site için geçerli olmadığı sürece HTTPS kullanmalıdır
  • Docset içinde bağlantı oluştururken
    • Göreli dosya yolu (../folder/file.md) kullanma
  • Tüm yollar ileri eğik çizgi (/) karakterlerini kullanır
  • Resim bağlantılarının benzersiz alternatif metni olmalıdır