Bazel'in dokümanlarına katkıda bulunduğunuz için teşekkür ederiz. Bu, başlamanıza yardımcı olacak hızlı bir belgeleme stil kılavuzudur. Stille ilgili bu kılavuzda yanıtlanmayan sorular için Google geliştirici belgeleri stil kılavuzundaki talimatları uygulayın.
İlkeleri tanımlama
Bazel dokümanları şu ilkeleri uygulamalıdır:
- Kısa ve öz. Mümkün olduğunca az kelime kullanın.
- Temizle. Sade bir dil kullanın. Beşinci sınıf okuma seviyesi için 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 gelecek vaatlerinden kaçınarak içeriğin mümkün olduğunca uzun süre doğru kalacağı şekilde yazın.
Yazım
Bu bölümde, yazmayla ilgili temel ipuçları yer almaktadır.
Başlık
- Sayfa düzeyi başlıklar H2'den başlar. (H1 başlıkları sayfa başlığı 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ıklar için normal tümce düzeni kullanın
- Evet: Çalışma alanınızı ayarlayın
- Hayır: Çalışma alanınızı 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 isimlerin büyük harf kullanımını yapın.
- Evet: Derlemenin sonunda, Bazel 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ğunda 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, okuyucuların ihtiyaç duydukları bilgiyi daha hızlı bulmalarına yardımcı olur.
- 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 bundan sonra ne yapması gerektiğini söyleyin. Net bir işlemin olmadığı sayfalar için benzer kavramlara, örneklere veya başka keşif alanlarına bağlantılar 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.
Okuyucunuza "siz" hitap etmek. (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.
- OLABİLİR: Kullanıcıların Bazel ile Java kodu oluşturabilmeleri için bir JDK yüklemesi 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) gibi. Bunlar kısa sürede eskir ve gelecekteki bir projeksiyon ise yanlış olabilir. Bunun yerine, bunun yerine bir sürüm düzeyi belirtin. Örneğin, "Bazel X.x ve sonraki sürümler <feature> özelliğini veya GitHub sorun bağlantısını destekler.
- 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 açısından 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 özneye bir özne tarafından hareket ettirildiğinde). Genellikle aktif ses, kimin sorumlu olduğunu gösterdiği için cümleleri daha anlaşılır hale getirir. Etken çatı kullanmak netliği azaltıyorsa pasif ses 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 daha sonra, Y çıktıyla 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. Teknolojiyi merak eden ama ayrıntıları bilmeyen birine kavramı açıklıyormuş gibi yazın.
Biçimlendirme
Dosya türü
Okunabilirlik için satırları 80 karakter olacak şekilde kaydırı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 bilgiyi [burada] bulabilirsiniz.
Mümkünse cümleyi bağlantıyla sonlandırın.
- Evet: Daha fazla bilgi için [link] sayfasına bakın.
- Hayır: Daha fazla bilgi için [link] adresine bakın.
Listeler
- Bir görevin nasıl tamamlanacağını adımlarla açıklamak için sıralı bir liste kullanın
- Göreve dayalı olmayan öğeleri listelemek için sıralanmamış bir liste kullanın. (Yine de alfabetik, önem vb. gibi bir sıralama olması gerekir.)
- Paralel yapıyla yazma. Örneğin:
- Tüm liste öğesi cümlelerini oluşturun.
- 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 komut: "Komut" için yardım ve seçenekleri yazdırır.
- Evet:
Özellikle karmaşık kod örnekleri için bağlam içinde anlamlı olan yer tutucular kullanın.
İçindekiler
Site tarafından desteklenen otomatik olarak oluşturulmuş TOC'yi kullanın. Manuel TOC eklemeyin.
Kod
Kod örnekleri, geliştiricilerin en iyi dostudur. Muhtemelen bunları nasıl yazacağınızı biliyorsunuzdur ama size birkaç ipucu verebiliriz.
Küçük bir kod snippet'inden bahsediyorsanız kodu cümleye yerleştirebilirsiniz. Okuyucunun kodu kullanmasını istiyorsanız (ör. komut kopyalamak) istiyorsanız kod bloğu kullanın.
Kod blokları
- Fragmanı kısa tutun. Bir kod örneğindeki tüm gereksiz veya gereksiz 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" veya kalın yazı tipi 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 komut: "Komut" için yardım ve seçenekleri yazdırır.
- Evet: