Programlama dilini belgeleme: Referans Kılavuzu

Ürün yelpazemizdeki dokümantasyonun yenilenmesine bakıyoruz. Bunun bir kısmı, sistemin bir parçası olarak kullanılan bir programlama dili için referans kılavuzları içerir .

Bir programlama dili için referans kılavuzu yazarken, dili yeni olanlar için maksimum kullanılabilirlik için yapılandırmanın en iyi yolu nedir?

Belgelenen her bir anahtar kelimenin temel özellikleri nelerdir ?

• Sözdizimi
• Açıklama
• Bağımsız değişkenler - varsa
• Dönüş değerleri - varsa
• Kullanım örneği?
• Kayıp ettiğim başkaları var mı?

Kavramlar (kilitleme stratejileri, performansla ilgili ayrıntılar gibi) de bu başvuru kılavuzunda belgelenmeli mi yoksa ayrı bir belge mi?

---

_{Bu harici tüketim içindir. Zaten tam doküman setlerimiz var (bkz . Http://www.rocketsoftware.com/u2/resources/technical-resources ). Neyi farklı yapmamız gerektiğini bulmak - fikirlerim zaten var, ama her zaman olduğu gibi, sadece fikrime güvenmemeye çalışıyorum.}

_{Kitle: Birçok sektörde yazılım üretmek için veritabanlarımızı ve araçlarımızı kullanan teknik geliştiriciler.}

Belgeleri hedef kitle ihtiyaçlarına göre düzenleyin.

Sizin durumunuzda, birincil kitle görünüşe göre yazılım geliştiricilerdir. Burada dikkate alınması gereken kısımlar, bunun farklı "alt kitlelerine" yöneliktir:

1. Selam Dünya.
   Hızla tadını almak isteyenler, sadece nasıl göründüğünü görmek için örnek uygulama oluşturmak ve çalıştırmak.
   Kitleyi MySQL "15 dakika kuralı" ile ele alınan gibi düşünün :
   

   _{... bir kullanıcının MySQL'i indirip yüklemeyi bitirdikten 15 dakika sonra çalıştırabilmesi.}

2. Temelleri.
   Çalışma yazılımı üretmeye başlamak için gerekli şeyleri hızlı bir şekilde öğrenmek isteyen çocuklar için.
3. Gelişmiş konular.
   Zaten iyi bilinen ve temelleri ile pratik geliştiriciler, ötesinde neler olduğunu bilmek isteyen. Kaplı henüz ana akım konular Temel .
4. Stil Kılavuzu / Önerilen Uygulamalar.
   Bir şeyler yapmayı nasıl önereceğinizle ilgilenenler için subjektif tavsiye ve rehberlik.
   _{Soru, bunun sizin durumunuzda önemli bir kitleye sahip olup olamayacağını göstermez, bu nedenle dikkate alınması gereken seçenekler, bunu Gelişmiş konuların bir parçası / eki ​​olarak dahil etmek veya hatta tamamen bırakmaktır.}
5. Gariplikleri.
   Ana akımın dışında, kitlenizin oldukça sınırlı bir kısmının ilgisini çekebilecek belirsiz konular. Örneğin, eski satırınız veya eski sürümle yükseltme / taşıma / birlikte çalışabilirlik gibi bir şey varsa, buraya koyun. Belirli "egzotik" ortamdaki bazı fonksiyonlar için bazı yan etkiler varsa, bu kısımdan geçer.

İkincil kitleniz bu kılavuzun koruyucusudur. Bu adamlar birincil kitleniz için işlerin nasıl işlediğini yapabilir veya bozabilir, böylece onların ihtiyaçlarını ve sorunlarını daha iyi halledebilirsiniz.

^{Kılavuzdaki bir şey şüpheli / belirsizse ne olur? Belirli kavramların kapsamlı bir şekilde açıklanmasının bu kılavuzu okumayı çok zorlaştıracağı ortaya çıkarsa ne olur? Kılavuzun belirli versiyonunda hatalar olduğu ortaya çıkarsa ne olur?}

Koruyucular için dikkate alınması gereken iki şey:

1. Teknik / resmi şartname.
   Kılavuzda şüpheli / belirsiz / açıklanması zor bir konu olduğunda, okuyucu, bu konuda katı ve açık, "resmi" bir açıklama için spesifikasyondaki belirli paragraflara yönlendirilebilir. Dil sözdiziminin katı ve eksiksiz (ve büyük olasılıkla sıkıcı) açıklaması oraya gitmek daha iyi olur. Şartname için en
   önemli hususlar , okunabilirlik pahasına olsalar bile, teknik doğruluk ve bütünlüktür.
2. Çevrimiçi ek.
   Sadece bir URL ayırın ve serbest bıraktığınız her belgenin başına koyun, böylece az önce okuduklarını merak eden çocuklar oraya gidebilirler (manuel bakımcıları rahatsız etmek yerine) ve açıklanan hatayı bulabilirler.

   _{Errata> Temel Bilgiler> Sürüm 2.2> Yazım hatası sayfa 28, ikinci cümle şansla başlar , bunun yerine kilidi oku .}

Kilitleme stratejileri, performansla ilgili ayrıntılar gibi kavramlar, hedef kitlenin buna ihtiyaç duyacağı yerlere dahil edilmelidir (kısmen mümkündür).

Örneğin, manuel bakımcılar görünüşte eşzamanlılığın tam ve doğru bir tanımıyla ve resmi spesifikasyonda kilitlenmeyle ilgileneceklerdi - oraya koy. Temel Bilgiler veya İleri düzey konulardaki okuyucular, şartnameden çıkarılan ve ihtiyaçlarına göre uyarlanmış bir genel bakış / tanıtım / kılavuzla ilgilenebilir.

---

_{Sizinki gibi diğer diller için sağlanan referans belgelerin karşılaştırmalı bir çalışmasının düzenlenmesi yararlı olabilir. Bu çalışmayı, daha önce yapanlar tarafından kazanılan deneyimden yararlanmaya ve yaptıkları hatalardan nasıl kaçınacaklarını öğrenmeye yöneltin.}

_{Sonuncusu ama en önemlisi, yazılım geliştirmeye benzer bir şekilde dokümantasyon geliştirmeyi düşünün. Sürüm kontrolü, düzenli sürümler, sorun izleme, kalite güvencesi vb. Şeyleri kastediyorum. Teknik yazarlarınızın bu tür şeylerle gerçekten rahat olmadığı ortaya çıkarsa, bazı tavizler vermek isteyebilirsiniz. Mükemmel geliştirme süreci için "karşılığında" berbat içerik almak istemiyoruz, değil mi?}

Yapmanız gereken ilk şey, kitleyi değerlendirmektir. Kitleniz Linux çekirdeği korsanları mı yoksa bir iş yapmak için yazılım araçlarını kullanan ancak kendi başlarına yazılımla ilgilenmeyen ve CS geçmişi olmayan donanım tasarımcıları mı? Elektrik mühendisleri, const ve const olmayan argümanlar, nesnelere referanslara karşı işaretler, vb. Arasındaki farklar konusunda tam olarak açık olmayacaklardır. C ++ programcıları ise hiçbir şey olmayabilir.

Değerlendirmeniz gereken ikinci şey, dilin ilkellerinin ayrıntısıdır. Taneciklik ne kadar ince olursa, her bir ilkenin sözdizimi spesifikasyonlarına yakın olarak kullanım örnekleri sunmanız gerekecektir. Yani, bir bağlamı başlatan düşük seviyeli bir ilkeliniz varsa ve yararlı bir şey yapmadan önce üzerinde diğer üç düşük seviyeli ilkel ile çalışmanız gerekiyorsa, o zaman bazı yararlı işlevlerin tam bir örneğine sahip olsanız iyi olur. tarafından. Neredeyse kullanılamayan belgelerin mükemmel bir karşı örneği için çevrimiçi openssl belgelerine bakın .

İşlevlerinizin herhangi bir yan etkisi hakkında açıklama eklediğinizden emin olun .

Her halükarda, müşterinizin programcılarının yatmadan önce her gece sizi lanetlemesini istemiyorsanız, bazı üst düzey fonksiyonel ilkeleri gerçekleştiren test edilmiş örnek kodlar ekleyin. Örneklerin yalnızca kod snippet'leri değil, aynı zamanda eksiksiz ve derlenebilir veya çalıştırılabilir hazır olduğundan emin olun.

Geleneksel olarak, teknoloji yazarları referans kılavuzları ve kullanıcı kılavuzları arasında ayrım yapmıştır . Referans el kitabı genellikle sözdizimi özelliklerini, işlevlerin veya ilkellerin anlaşılır bir tanımını, gotcha'nın tartışmasını, performans ve yan etkileri ve kısa bir örnek kullanımını içerir. Kullanıcı kılavuzu daha geniş kullanım örnekleri ve daha geniş mühendislik konularının tartışılmasını içerir. Kernigan ve Ritchie "C Programlama Dili" bu sözleşmenin mükemmel bir karşı örneğidir, ancak bu yaklaşım yalnızca belgelediğiniz dil nispeten basit olduğunda işe yarar.

Yazar, 1987-1991 yılları arasında Ready Systems Inc'in geliştirme merkezinde Mühendislik Hizmetleri Bölümü'nün beş teknik yazardan oluşan bir ekibin yönetiminden sorumluydu.