Bazel belgelerine katkıda bulunduğunuz için teşekkür ederiz. Bu, başlamanıza yardımcı olacak hızlı bir belgeleme stil kılavuzudur. 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 uygulamalı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ı olun. Dokümanlar genelinde tekrarlanan kavramlar için aynı kelimeleri veya ifadeleri 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.)
Üstbilgileri mümkün olduğunca kısa tutun. Bu şekilde, sarmalama olmadan içine yerleşirler.
- 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ı ayarlayın
- Hayır: Workspace'inizi kurun
Başlıkları göreve dayalı veya uygulanabilir hale getirmeye çalışın. Başlıklar kavramsalsa, anlamayı temel alıyor olabilir ancak kullanıcının ne yaptığına uygun şekilde yazın.
- Evet: Grafik sırası korunuyor
- Hayır: Grafik sırasının korunması hakkında
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 kavramlara yeni adlar vermeyin. Uygun olduğu durumlarda Sözlük'te tanımlanan terimi kullanın.
- Örneğin, terminalde komut verme hakkında yazıyorsanız sayfada hem terminal hem de komut satırını kullanmayın.
Sayfa kapsamı
Her sayfanın bir amacı olmalıdır ve bu amacı başlangıçta tanımlanmalıdır. Bu sayede okuyucular aradıklarını daha hızlı bulabilir.
- Evet: Bu sayfada, Windows'a Bazel'in 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 belgelerinde hedef kitle öncelikle kullanıcılar, yani yazılımlarını geliştirmek için Bazel'i kullananlar olmalıdır.
Okuyucunuzu "siz" olarak hitap edin. (Herhangi bir nedenden dolayı "siz" ifadesini kullanamıyorsanız onlar gibi cinsiyet içermeyen bir dil kullanın.)
- Evet: Bazel kullanarak Java kodu oluşturmak 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 oluşturabilmesi için bir JDK yüklemesi gerekir.
Kitleniz genel Bazel kullanıcıları DEĞİLSE kitleyi sayfanın başında veya bölümde tanımlayın. Diğer kitleler arasında bakım görevlileri, katkıda bulunanlar, taşıyıcılar veya diğer roller yer alabilir.
"Biz" demekten kaçının. Kullanıcı dokümanlarında yazar yoktur. Sadece kullanıcılara neyin mümkün olduğunu söyleyin.
- Evet: Bazel geliştikçe uyumluluğu korumak için kod tabanınızı güncellemeniz gerekir.
- Hayır: Bazel gelişiyor. Zaman zaman uyumsuz olacak ve Bazel kullanıcılarının bazı değişiklikleri yapmasını gerektirecek değişiklikler yapacağız.
Geçici
Mümkün olduğunca, belirli tarihleri ima eden ya da "şimdi", "şu anda" veya "yakında" gibi ifadeleri zamana yayan terimlerden kaçının (2022 2. çeyrek) veya “şimdi” gibi ifadeler. Bunlar kısa sürede eskir ve gelecekteki bir projeksiyon ise 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, Ekim 2017'de uzaktan önbelleğe almayı yakında destekleyecektir.
Gergin
Şimdiki zaman kullanın. Anlaşılırlık için kesinlikle gerekli olmadığı sürece geçmiş veya gelecek zamanlardan 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 Bazel hata verir.
Mümkün olduğunda pasif ses yerine etken çatı kullanın (bir özne bir nesneye etki ettiğinde) (bir özne bir objeye karşı harekete geçtiğinde). 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 oluşturmak için çıkışı kullanır.
- Hayır: X, Bazel tarafından başlatılır ve ardından Y, çıkışla oluşturulur.
Ton
İş dostu bir üslup kullanarak yazın.
Konuşma dili kullanmaktan kaçının. İngilizceye özgü ifadeleri çevirmek daha zordur.
- Evet: İyi kural kümeleri
- Hayır: Peki, iyi kural kümesi nedir?
Fazla 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 kırpın. Uzun bağlantılar veya kod snippet'leri daha uzun olsa da yeni bir satırla 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ümanları taramayı kolaylaştırır ve ekran okuyucular için daha uygundur.
- Evet: Daha ayrıntılı bilgi için [Bazel'i Yükleme] sayfasına bakın.
- Hayır: Daha fazla bilgi için [buraya] bakın.
Mümkünse cümleyi bağlantıyla sonlandırın.
- Evet: Daha fazla bilgi için [bağlantı] bölümüne bakın.
- Hayır: Daha fazla bilgi için [link] adresine bakın.
Listeler
- Bir görevin nasıl tamamlanacağını adımlar halinde açıklamak için sıralı bir liste kullanma
- Göreve dayalı olmayan öğeleri listelemek için sıralanmamış bir liste kullanın. (Yine de alfabetik, önem vb. gibi bir sıralama düzeni olmalıdır.)
- Paralel yapıyla yazın. Örneğin:
- Liste öğelerinin tümünü cümle haline getirin.
- Aynı zaman fiilleriyle başlayın.
- İzlenecek adımlar varsa sıralı bir liste kullanın.
Yer tutucular
Kullanıcıların değiştirmesi gereken bir değişkeni göstermek için açılı ayraç kullanın. Markdown'da, açılı ayraçlardan ters eğik çizgiyle çıkış yapın:
\<example\>.- Evet:
bazel help <command>:<command>ile ilgili yardım ve seçenekleri yazdırır - 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ı 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'inden bahsediyorsanız kodu 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ışları 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 kalın yazı yerine satır içi kod stilini kullanın.
- Evet:
bazel help <command>:<command>ile ilgili yardım ve seçenekleri yazdırır - Hayır: bazel help command: "command" için yardım ve seçenekleri yazdırır
- Evet: