Bazel belgelerine katkıda bulunduğunuz için teşekkür ederiz. Bu, başlangıç için kısa bir doküman stili kılavuzu niteliğindedir. Bu kılavuzda yanıtlanmayan stil soruları için Google geliştirici belgeleriyle ilgili stil kılavuzunu inceleyin.
İlkeleri tanımlama
Bazel dokümanları şu ilkeleri karşılamalıdır:
- Kısa. Mümkün olduğunca az kelime kullanın.
- Temizle. Sade bir dil kullanın. Beşinci sınıf okuma seviyesine uygun şekilde jargon kullanmadan yazın.
- Tutarlı. Belgelerde tekrarlanan kavramlar için aynı kelimeleri veya kelime öbeklerini kullanın.
- Doğru. Zamana dayalı bilgilerden ve gelecekle ilgili vaatlerden kaçınarak içeriğin mümkün olduğunca uzun süre doğru kalacağı şekilde yazın.
Yazma
Bu bölümde temel yazma ipuçları yer almaktadır.
Başlıklar
- Sayfa düzeyindeki başlıklar H2 ile başlar. (H1 başlıkları sayfa başlıkları olarak kullanılır.)
Başlıkları mümkün olduğunca kısa tutun. Bu şekilde, satır başı işaretleri satır hizasına sığdırılabilir.
- Evet: İzinler
- Hayır: İzinlerle ilgili kısa bir not
Başlıklarda büyük harf kullanın
- Evet: Çalışma alanınızı kurun
- Hayır: Workspace'inizi kurun
Başlıkları görev tabanlı veya işlem yapılabilir hale getirmeyi deneyin. Başlıklar kavramsalsa anlama odaklı olabilir ancak kullanıcının ne yaptığını da yazın.
- Evet: Grafik sırasını koruma
- Hayır: Grafik sırasının korunması
Adlar
Bazel ve Starlark gibi özel adları büyük harfle yazın.
- Evet: Bazel, derlemenin sonunda istenen hedefleri yazdırır.
- Hayır: Derlemenin sonunda bazel, istenen hedefleri yazdırır.
Tutarlı olmasına dikkat edin. Mevcut kavramlar için yeni adlar kullanmayın. Uygun olduğu durumlarda Sözlük'te tanımlanan terimi kullanın.
- Örneğin, bir terminalde komut verme hakkında yazıyorsanız sayfada hem terminali hem de komut satırını kullanmayın.
Sayfa kapsamı
Her sayfanın bir amacı olmalı ve bu amaç baştan tanımlanmalıdır. Bu sayede okuyucular aradıklarını daha hızlı bulabilir.
- Evet: Bu sayfada, Bazel'in Windows'a nasıl yükleneceği açıklanmaktadır.
- Hayır: (Giriş cümlesi yok.)
Sayfanın sonunda okuyucuya ne yapacağını söyleyin. Net bir işlem bulunmayan sayfalara benzer kavramların, örneklerin veya keşfedilebilecek diğer yolların bağlantılarını ekleyebilirsiniz.
Konu
Bazel dokümanlarında kitle öncelikle kullanıcılar (yazılımlarını oluşturmak için Bazel'i kullanan kişiler) olmalıdır.
Okuyucunuzu "siz" olarak hitap edin. (Herhangi bir nedenle "siz"i kullanamıyorsanız cinsiyet belirtmeyen bir dil kullanın.)
- Evet: Bazel'i kullanarak Java kodu derlemek için bir JDK yüklemeniz gerekir.
- OLASI: Kullanıcıların Bazel ile Java kodu derleyebilmesi için bir JDK yüklemeleri gerekir.
- Hayır: Bir kullanıcının Bazel ile Java kodu derleyebilmesi için JDK yüklemesi gerekir.
Kitleniz genel Bazel kullanıcıları DEĞİLSE sayfanın başında veya bölümde kitleyi tanımlayın. Diğer kitleler arasında geliştiriciler, katkıda bulunanlar, taşıyıcılar veya diğer roller yer alabilir.
"Biz" ifadesini kullanmaktan kaçının. Kullanıcı dokümanlarında yazar yoktur. Kullanıcılara nelerin mümkün olduğunu belirtin.
- Evet: Bazel geliştikçe uyumluluğu korumak için kod tabanınızı güncellemeniz gerekir.
- Hayır: Bazel gelişiyor ve Bazel'de bazen uyumlu olmayan ve Bazel kullanıcılarının bazı değişiklikler yapması gereken değişiklikler yapacağız.
Zamansal
Mümkün olduğunda, belirli tarihlere (2022'nin 2. çeyreği) atıfta bulunma veya "şimdi", "şu anda" ya da "yakında" gibi zamana dayalı terimlerden kaçının. Bu veriler hızla eskir ve gelecekle ilgili bir tahminse yanlış olabilir. Bunun yerine, "Bazel X.x ve sonraki sürümler <özellik>yi destekler" gibi bir sürüm düzeyi belirtin veya GitHub sorun bağlantısı ekleyin.
- Evet: Bazel 0.10.0 veya sonraki sürümler uzaktan önbelleğe almayı destekler.
- Hayır: Bazel yakında uzaktan önbelleğe alma özelliğini destekleyecek. Bu özellik muhtemelen Ekim 2017'de kullanıma sunulacak.
Gergin
Şimdiki zaman kullanın. Anlaşılırlık için kesinlikle gerekli olmadığı sürece geçmiş veya gelecek zaman kipini kullanmaktan kaçının.
- Evet: Bazel, bu kurala uymayan bağımlılıklar bulduğunda hata verir.
- Hayır: Bazel bu kurala uymayan bir bağımlılık bulursa hata verir.
Mümkün olduğunda edilgen değil etken ses kullanın (etken ses, öznenin bir nesneyi etkilediği durumlarda kullanılır). Genellikle etken çatı, sorumlu olan kişiyi gösterdiği için cümleleri daha net hale getirir. Etken yapı kullanmak netliği bozuyorsa edilgen yapı kullanın.
- Evet: Bazel, X'i başlatır ve Y'yi derlemek için çıkışı kullanır.
- Hayır: X, Bazel tarafından başlatılır ve ardından Y, çıkışla oluşturulur.
Ton
İşletmelere uygun bir üslup kullanın.
Argo dil kullanmaktan kaçının. İngilizceye özgü ifadeleri çevirmek daha zordur.
- Evet: İyi kural kümeleri
- Hayır: Peki iyi bir kural kümesi nedir?
Aşırı resmi bir dil kullanmaktan kaçının. Kavramı, teknolojiye meraklı ancak ayrıntıları bilmeyen birine açıklıyormuş gibi yazın.
Biçimlendirme
Dosya türü
Okunabilirlik için satırları 80 karakterde kaydırın. Uzun bağlantılar veya kod snippet'leri daha uzun olabilir ancak yeni bir satırda başlamalıdır. Örneğin:
Bağlantılar
"Burada" veya "Aşağıda" yerine açıklayıcı bağlantı metni kullanın. Bu uygulama, dokümanı taramayı kolaylaştırır ve ekran okuyucular için daha iyidir.
- Evet: Daha fazla bilgi için [Bazel'i yükleme] bölümüne bakın.
- Hayır: Daha fazla bilgi için [buraya] bakın.
Mümkünse cümleyi bağlantıyla bitirin.
- Evet: Daha fazla bilgi için [bağlantı] bölümüne bakın.
- Hayır: Daha fazla bilgi için [bağlantı] sayfasına bakın.
Listeler
- Bir görevi adım adım nasıl tamamlayacağınızı açıklamak için sıralı liste kullanın
- Görev tabanlı olmayan öğeleri listelemek için sırasız liste kullanın. (Alfabetik, önem vb. bir sıralama yine de olmalıdır.)
- Paralel yapıyla yazın. Örneğin:
- Tüm liste öğelerini cümle haline getirin.
- Aynı zaman kipindeki fiillerle başlayın.
- Uygulanması gereken adımlar varsa sıralı bir liste kullanın.
Yer tutucular
Kullanıcıların değiştirmesi gereken bir değişkeni belirtmek için köşeli parantez kullanın. Markdown'da köşeli parantezleri ters eğik çizgiyle kaçış karakteri olarak kullanın:
\<example\>.- Evet:
bazel help <command>:<command>için baskı yardımı ve seçenekler - Hayır: bazel help command: "command" için yardım ve seçenekleri yazdırır
- Evet:
Özellikle karmaşık kod örnekleri için bağlamda anlamlı olan yer tutucular kullanın.
İçindekiler
Site tarafından desteklenen otomatik olarak oluşturulan içindekiler bölümünü kullanın. Manuel bir içindekiler listesi eklemeyin.
Kod
Kod örnekleri, geliştiricilerin en iyi dostlarıdır. Bu tür içerikleri nasıl yazacağınızı zaten biliyorsunuzdur ancak yine de birkaç ipucu verelim.
Küçük bir kod snippet'ine referans veriyorsanız bunu bir cümleye yerleştirebilirsiniz. Okuyucunun kodu kullanmasını istiyorsanız (ör. bir komutu kopyalamak için) kod bloğu kullanın.
Kod blokları
- Kısa tutun. Kod örneğindeki tüm gereksiz veya istenmeyen metinleri kaldırın.
- Markdown'da, örneğin dilini ekleyerek kod bloğunun türünü belirtin.
```shell
...
- Komutları ve çıkışı farklı kod bloklarına ayırın.
Satır içi kod biçimlendirmesi
- Dosya adları, dizinler, yollar ve küçük kod parçaları için kod stilini kullanın.
- İtalik, "tırnak işareti" veya bolding yerine satır içi kod stilini kullanın.
- Evet:
bazel help <command>:<command>için baskı yardımı ve seçenekler - Hayır: bazel help command: "command" için yardım ve seçenekleri yazdırır
- Evet: