Bazel'ın dokümanlarına katkıda bulunduğunuz için teşekkür ederiz. Bu kılavuz, başlamanıza yardımcı olacak hızlı bir belge stili kılavuzu görevi görür. Bu kılavuzda yanıtlanmayan tüm 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 ve öz. Mümkün olduğunca az kelime kullanın.
- Temizle. Düz dil kullanın. Beşinci sınıf okuma seviyesi için jargon olmadan yazın.
- Tutarlı olun. Dokümanlar genelinde tekrarlanan kavramlar için aynı kelimeleri veya kelime öbeklerini kullanın.
- Doğru. Zamana dayalı bilgilerden ve gelecek vaadinden 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 temel yazma ipuçları yer almaktadır.
Başlık
- Sayfa düzeyi başlıklar H2'de 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, sarmalama olmadan Belgeye sığarlar.
- Evet: İzinler
- Hayır: İzinler hakkında kısa bir not
Başlıklar için cümle düzeni kullanın
- Evet: Çalışma alanınızı ayarlayın
- Hayır: Çalışma Alanınızı Ayarlayın
Başlıkları göre işleme veya harekete geçirmeye çalışın. Başlıklar kavramsalysa anlamaya dayalı olabilir, ancak kullanıcının ne yaptığını yazın.
- Evet: Grafik sırasını koruma
- Hayır: Grafik sırasının korunması durumunda
Adlar
Bazel ve Starlark gibi özel isimleri büyük harfle yazın.
- Evet: Yapının sonunda Bazel istenen hedefleri bastırır.
- Hayır: Derlemenin sonunda site, istenen hedefleri bastırır.
Tutarlı olmasına dikkat edin. Mevcut kavramlar için yeni adlar vermeyin. Uygun durumlarda, Sözlük bölümünde belirtilen terimi kullanın.
- Örneğin, bir terminalde komut verme hakkında yazıyorsanız sayfada hem terminal hem de komut satırı kullanmayın.
Sayfa kapsamı
Her sayfanın tek bir amacı olmalıdır ve başlangıçta tanımlanmış olmalıdır. Bu, okuyucuların ihtiyaç duydukları şeyi daha hızlı bulmalarına yardımcı olur.
- Evet: Bu sayfada Bazel'ın Windows'a nasıl yükleneceği açıklanmaktadır.
- Hayır: (Tanıtım cümlesi yok.)
Sayfanın sonunda, okuyucuya bir sonraki adımda ne yapması gerektiğini söyleyin. Net bir işlemin olmadığı sayfalara benzer kavramların, örneklerin veya diğer keşif yollarının bağlantılarını ekleyebilirsiniz.
Konu
Bazel dokümanlarında kitle, birincil olarak kullanıcılar, yani yazılımlarını oluşturmak için Bazel'i kullanan kişiler olmalıdır.
Okuyucunuza "siz" olarak hitap edin. (Herhangi bir nedenle "siz"i kullanamıyorsanız cinsiyet gibi tarafsız bir dil kullanın. Örneğin,
- Evet: Bazel kullanarak Java kodu oluşturmak için bir JDK yüklemeniz gerekir.
- BELKİ: Kullanıcıların Bazel ile Java kodu oluşturabilmeleri için JDK yüklemeleri gerekir.
- Hayır: Kullanıcının Bazel ile Java kodu oluşturabilmesi için 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 bakanlar, katkıda bulunanlar, göçmenler veya diğer roller yer alabilir.
"Biz"den kaçının. Kullanıcı dokümanlarında yazar yok; 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şmektedir ve Bazel'da yapılan değişiklikler bazı zamanlarda uyumsuz hale gelecektir ve Bazel kullanıcılarının bazı değişiklikler yapmasını gerektirecektir.
Geçici
Mümkün olduğunda, belirli tarihlere atıfta bulunma (2022 2. çeyrek) veya "hemen", "şu anda" veya "yakında" gibi ifadeler içeren terimlerden kaçının. Bu bilgiler hızla eskir ve gelecekteki bir projeksiyonsa yanlış olabilir. Bunun yerine, "Bazel X.x ve sonraki sürümler <feature> veya GitHub sorunu bağlantısını destekler gibi bir sürüm düzeyi belirtin.
- Evet: Bazel 0.10.0 veya sonraki sürümler uzaktan önbelleğe almayı destekler.
- Hayır: Bazel yakında Ekim 2017'de uzaktan önbelleğe almayı destekleyecek.
Gergin
Şu anki zamanı kullan. Netlik için kesinlikle gerekli olmadığı sürece geçmişteki veya gelecekteki 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 hata verir.
Mümkün olduğunda pasif ses değil, özne (nesneye göre bir nesne üzerinde işlem yapılır) ses kullanın. Genellikle, kimin sorumlu olduğunu gösteren aktif sesler cümleleri daha anlaşılır hale getirir. Aktif sesi açık bir şekilde kullanamıyorsanız pasif ses kullanın.
- Evet: Bazel X'i başlatır ve çıkışı kullanarak Y'yi oluşturur.
- Hayır: X, Bazel tarafından başlatılır ve daha sonra Y, çıkışla oluşturulur.
Ton
İş dostu bir üslup ile yazın.
Konuşma dilinden kaçının. İngilizceye özgü kelime öbeklerini çevirmek daha zordur.
- Evet: İyi kurallar
- Hayır: Peki iyi bir kural kümesi nedir?
Fazla resmi ifadeler kullanmayın. Teknolojiyi merak eden ancak ayrıntıları bilmeyen birine konsepti açıklıyormuş gibi yazın.
Biçimlendirme
Dosya türü
Okunabilirlik için satırları 80 karakter boyunca sarmalayı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 bir dokümanı taramayı kolaylaştırır ve ekran okuyucular için daha iyidir.
- Evet: Daha fazla bilgi için [Banzel Yükleme] konusuna bakın.
- Hayır: Ayrıntılı bilgi için [burayı] inceleyin.
Mümkünse cümleyi bağlantıyla sonlandırın.
- Evet: Daha fazla bilgi için [link] adresini ziyaret edin.
- Hayır: Daha fazla bilgi için [link] bağlantısını inceleyin.
Listeler
- Adımların bir görevi nasıl gerçekleştireceğini açıklamak için sıralı liste kullanma
- Göreve dayalı olmayan öğeleri listelemek için sıralanmamış bir liste kullanma. (Yine de alfabetik sıra, önem vb. gibi bir sıralama olmalıdır)
- Paralel yapıyla yazın. Örneğin:
- Tüm liste öğelerini cümleler haline getirin.
- Aynı zamana ait fiillerle başlayın.
- Uygulamanız gereken adımlar varsa sıralı 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 kod dışına alın:
\<example\>.- Evet:
bazel help <command>:<command>için yardım ve seçenekleri yazdır - Hayır: bazel yardım komutu: Yazdırma yardımı ve "komut" seçenekleri
- Evet:
Özellikle karmaşık kod örnekleri için bağlam açısından anlamlı yer tutucular kullanın.
İçindekiler
Site tarafından desteklenen otomatik oluşturulan TO'yu kullanın. Manuel TO eklemeyin.
Kod
Kod örnekleri, geliştiricilerin en iyi arkadaşlarıdır. Muhtemelen bunları nasıl yazacağınızı bileceksiniz ancak burada birkaç ipucu bulabilirsiniz.
Küçük bir kod snippet'inden bahsediyorsanız bunu bir cümleye yerleştirebilirsiniz. Okuyucunun, kodu kopyalama gibi bir kod kullanmasını istiyorsanız bir kod bloğu kullanın.
Kod blokları
- Fragmanı kısa tutun. Kod örneğindeki gereksiz veya gereksiz metinlerin tamamını 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 kalın metin yerine satır içi kod stili kullanın.
- Evet:
bazel help <command>:<command>için yardım ve seçenekleri yazdır - Hayır: bazel yardım komutu: Yazdırma yardımı ve "komut" seçenekleri
- Evet: