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 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ı. 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, 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ı kurun
- 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ını koruma
- 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ı olun. 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 bundan sonra ne yapması gerektiğini 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 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. 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 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 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 ç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 ardından Y, çıkışla oluşturulur.
Ton
İşletmelere uygun bir üslup kullanın.
Konuşma dili kullanmaktan kaçının. İngilizceye özgü ifadeleri çevirmek daha zordur.
- Evet: İyi kural kümeleri
- Hayır: Peki iyi bir 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 karakterde kırpı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 sonlandırın.
- 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. (Yine de alfabetik, önem vb. gibi bir sıralama düzeni olmalıdır.)
- Paralel yapıyla yazın. Ö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>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ğlam içinde 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. Muhtemelen bunları nasıl yazacağınızı biliyorsunuzdur ama size birkaç ipucu verebiliriz.
Küçük bir kod snippet'ine referans veriyorsanız bunu bir cümleye yerleştirebilirsiniz. Okuyucunun kodu kullanmasını istiyorsanız (ör. komut kopyalamak) istiyorsanız 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 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: