Aracılığıyla paylaş

PowerShell Cmdlet'leri için Yardım Yazma

PowerShell cmdlet'leri yararlı olabilir, ancak Yardım konularınız cmdlet'in ne yaptığını ve nasıl kullanılacağını açıkça açıklamadığı sürece, cmdlet kullanılmayabilir veya daha da kötüsü kullanıcıları rahatsız edebilir. XML tabanlı cmdlet Yardım dosyası biçimi tutarlılığı artırır, ancak çok daha fazla yardım gerektirir.

Cmdlet Yardımı'nı hiç yazmadıysanız aşağıdaki yönergeleri gözden geçirin. Cmdlet Yardım konusunu yazmak için gereken XML şeması aşağıdaki bölümde açıklanmıştır. cmdlet Yardım Dosyasını oluşturma ile başlayın. Bu konu, üst düzey XML düğümlerinin açıklamasını içerir.

Cmdlet Yardımı için Yönergeler Yazma

İyi yaz

İyi yazılmış bir konunun yerini hiçbir şey değiştirmez. Profesyonel bir yazar değilseniz size yardımcı olacak bir yazar veya düzenleyici bulun. Bir diğer alternatif de Yardım metninizi Microsoft Word'e kopyalamak ve çalışmanızı geliştirmek için dil bilgisi ve yazım denetimi kullanmaktır.

Basitçe yazma

Basit sözcükler ve tümcecikler kullanın. Jargon'lardan kaçının. Birçok okuyucuda yalnızca yabancı dil sözlüğü ve Yardım konunuzun bulunduğunu düşünün.

Tutarlı yazma

İlgili cmdlet'ler için yardım benzer olmalıdır (örneğin, Get-Content ve Set-Content). Force ve InputObjectgibi standart parametreler için standart açıklamaları kullanın. (Bunları çekirdek cmdlet'leri için Yardım'dan kopyalayın.) Standart terimleri kullanın. Örneğin, "bağımsız değişken" yerine "parametre" kullanın ve "komut" veya "command-let" yerine "cmdlet" kullanın.

Fiil ile özete başlama

Özet alanı, cmdlet'in ne yaptığını veya nasıl çalıştığını değil, ne yaptığını kullanıcıya bildirir. Fiiller, bu cmdlet'in gereksinimlerini karşılayıp karşılamadığını kullanıcılara bildiren görev tabanlı bir deyim oluşturur. "Get", "create" ve "change" gibi basit fiiller kullanın. "Değiştir" gibi belirsiz ve süslü sözcükler olabilecek "set" sözcüğünden kaçının.

Nesnelere odaklanma

Çoğu "get" cmdlet'i bir şey görüntüler, ancak birincil işlevi bir nesne almaktır. Yardımınızda nesneye odaklanın, böylece kullanıcılar varsayılan görünümün çok sayıdan biri olduğunu anlayabilir ve onlar için aldığınız nesnenin yöntemlerini ve özelliklerini farklı şekillerde kullanabilirler.

Ayrıntılı açıklamalar yazma

Cmdlet'in gerçekleştirebileceği her şeyi ayrıntılı açıklamada kısaca listeleyin. Ana işlev bir özelliği değiştirmekse, ancak cmdlet tüm özellikleri değiştirebiliyorsa, bunu ayrıntılı açıklamada listeleyin.

Geleneksel söz dizimlerini kullanma

Windows ve Unix komut satırı Yardımı için ortak olan standart Backus-Naur biçimini kullanın.

Parametre değerleri için Microsoft .NET türlerini kullanma

Parametre değerlerinin yer tutucuları (söz diziminde ve parametre açıklamalarında), parametrenin kabul edeceği nesnelerin .NET Framework türlerini gösterir. PowerShell ekibi, kullanıcılara .NET Framework hakkında bilgi vermeye yardımcı olmak için bu kuralı geliştirdi.

Tam parametre açıklamaları yazma

Parametre açıklamaları kullanıcıları iki konuda bilgilendirmelidir: parametrenin ne yaptığı (etkisi) ve parametre değerleri için yazmaları gerekenler.

Pratik örnekler yazma

Örneklerde tüm parametrelerin nasıl kullanılacağı gösterilmelidir, ancak en önemli şey cmdlet'in gerçek dünyadaki görevlerde nasıl kullanılacağını göstermektir. Basit bir örnekle başlayın ve giderek daha karmaşık örnekler yazın. Son örnekte, bir işlem hattında cmdlet'in nasıl kullanılacağını gösterin.

Notlar alanını kullanma

Kullanıcıların cmdlet'ini anlaması gereken kavramları açıklamak için Notlar alanını kullanın. Notları, kullanıcıların yaygın hatalardan kaçınmasına yardımcı olmak için de kullanabilirsiniz. Url'ler değiştikçe kaçının. Bunun yerine, kullanıcılara aranacak terimleri sağlayın.

Yardımınızı test etme

Kodunuzu test ettiğiniz gibi Yardım'da da test edin. Arkadaşlarınızın ve iş arkadaşlarınızın Yardım içeriğinizi okumasını ve geri bildirim sağlamasını sağlayın. Ayrıca haber gruplarından geri bildirim talep edebilirsiniz.

Ayrıca Bkz.

  • Last updated on