Bazel'in dokümanlarına katkıda bulunduğunuz için teşekkür ederiz. Bu belge, hızlı bir başlangıç yapmanıza yardımcı olacak kısa bir doküman stil kılavuzu olarak hazırlanmıştır. Bu kılavuzda yanıtlanmayan stil soruları için Google geliştirici belgeleriyle ilgili stil kılavuzuna bakın.
İlkeleri tanımlama
Bazel dokümanları şu ilkelere uygun olmalıdır:
- Kısa ve öz olmalıdır. Mümkün olduğunca az kelime kullanın.
- Temizle'yi tıklayın. Sade bir dil kullanın. Beşinci sınıf okuma seviyesine uygun, jargon içermeyen bir metin yaz.
- Tutarlı. Dokümanlarda tekrar eden 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 kalmasını sağlayacak şekilde yaz.
Yazma
Bu bölümde temel yazma ipuçları yer alır.
Başlıklar
- Sayfa düzeyindeki başlıklar H2 ile başlar. (H1 başlıkları, sayfa başlığı olarak kullanılır.)
Başlıkları makul ölçüde kısa tutun. Bu şekilde, içerik tablosuna sığar ve kaydırılmaz.
- Evet: İzinler
- Hayır: İzinlerle ilgili kısa bir not
Başlıklarda normal cümle düzeni kullanın
- Evet: Çalışma alanınızı kurma
- Hayır: Workspace'inizi kurma
Başlıkları göreve dayalı veya harekete geçirici yapmaya çalışın. Başlıklar kavramsal ise anlayışa dayalı olabilir ancak kullanıcının yaptığı işe göre yazın.
- Evet: Grafik sırasını koruma
- Hayır: Grafik sırasının korunmasıyla ilgili
Adlar
Özel isimleri (ör. Bazel ve Starlark) büyük harfle yazı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 kavramlar için yeni adlar kullanmayın. Geçerli 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 terminal hem de komut satırı ifadelerini kullanmayın.
Sayfa kapsamı
Her sayfanın bir amacı olmalı ve bu amaç en başta tanımlanmalıdır. Bu sayede okuyucular, ihtiyaç duydukları bilgileri 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 bir sonraki adımda ne yapması gerektiğini söyleyin. Net bir işlemin olmadığı sayfalarda benzer kavramlara, örneklere veya keşfedilebilecek diğer alanlara bağlantılar 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.
Okuyucunuza "siz" diye hitap edin. (Herhangi bir nedenle "siz"i kullanamıyorsanız cinsiyet belirtmeyen bir dil kullanın, örneğin "onlar".)
- Evet: Bazel kullanarak Java kodu oluşturmak için JDK yüklemeniz gerekir.
- BELKİ: Kullanıcıların Bazel ile Java kodu oluşturabilmesi için JDK yüklemeleri gerekir.
- Hayır: Kullanıcıları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 bakımcılar, katkıda bulunanlar, taşıyıcılar veya diğer roller yer alabilir.
"Biz" kelimesini kullanmaktan kaçının. Kullanıcı belgelerinde yazar yoktur. Kullanıcılara yalnızca neler yapabileceklerini anlatın.
- Evet: Bazel geliştikçe uyumluluğu korumak için kod tabanınızı güncellemeniz gerekir.
- Hayır: Bazel gelişmeye devam ediyor. Bazel'de zaman zaman uyumsuz olacak ve Bazel kullanıcılarının bazı değişiklikler yapmasını gerektirecek değişiklikler yapacağız.
Temporal
Mümkün olduğunda, belirli tarihlere (2022'nin 2. çeyreği) atıfta bulunmak veya "şimdi", "şu anda" ya da "yakında" demek gibi zamanla ilgili yönlendirmeler içeren terimlerden kaçının. Bunlar hızla eski hale gelir ve gelecekteki bir projeksiyon söz konusuysa yanlış olabilir. Bunun yerine, "Bazel X.x ve sonraki sürümleri <feature> özelliğini destekler" gibi bir sürüm düzeyi veya GitHub sorun bağlantısı belirtin.
- Evet: Bazel 0.10.0 veya sonraki sürümler, uzak önbelleğe almayı destekler.
- Hayır: Bazel, uzaktan önbelleğe almayı yakında destekleyecek. Bu özellik büyük olasılıkla Ekim 2017'de kullanıma sunulacak.
Gergin
Geniş zaman kullanın. Netlik için kesinlikle gerekli olmadıkça geçmiş veya gelecek zaman kullanmayı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 çatı (bir nesnenin bir özne tarafından etkilenmesi) yerine etken çatı (bir öznenin bir nesne üzerinde işlem yapması) kullanın. Genellikle etken çatı, sorumluyu gösterdiği için cümleleri daha net hale getirir. Etken çatı kullanmak netliği azaltıyorsa edilgen çatı 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
İşletmeye uygun bir üslupla yazın.
Konuşma dilinden kaçının. İngilizceye özgü ifadeleri çevirmek daha zordur.
- Evet: İyi kural kümeleri
- Hayır: Peki iyi bir kural grubu nedir?
Aşırı resmi bir dil kullanmaktan kaçının. Teknolojiye meraklı ancak ayrıntıları bilmeyen birine kavramı açıklıyormuş gibi yaz.
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, belgelerin taranmasını kolaylaştırır ve ekran okuyucular için daha uygundur.
- Evet: Daha fazla bilgi için [Installing Bazel] başlıklı makaleyi inceleyin.
- 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ı] adresini ziyaret edin.
- Hayır: Daha fazla bilgi için [bağlantı] adresini ziyaret edin.
Listeler
- Bir görevin adımlarını açıklamak için sıralı liste kullanma
- Görev tabanlı olmayan öğeleri listelemek için sırasız liste kullanın. (Yine de alfabetik sıralama, önem sırası vb. gibi bir sıralama olmalıdır.)
- Paralel yapıyla yazın. Örneğin:
- Tüm liste öğelerini cümle haline getirin.
- Aynı zamanda olan fiillerle başlayın.
- İzlenecek 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
\<example\>kaçırın.- Evet:
bazel help <command>:<command>ile ilgili yardım ve seçenekler yazdırılır. - Hayır: bazel help command: "command" için yardım ve seçenekleri yazdırır.
- Evet:
Özellikle karmaşık kod örneklerinde, bağlamda anlamlı yer tutucular kullanın.
İçindekiler
Site tarafından desteklenen otomatik oluşturulmuş içindekiler tablosunu kullanın. Manuel içindekiler tablosu eklemeyin.
Kod
Kod örnekleri, geliştiricilerin en iyi dostudur. Bunları nasıl yazacağınızı biliyor olabilirsiniz ancak yine de birkaç ipucu paylaşmak istiyoruz.
Küçük bir kod snippet'ine referans veriyorsanız bunu bir cümleye yerleştirebilirsiniz. Okuyucunun kodu kullanmasını (ör. komut kopyalama) istiyorsanız kod bloğu kullanın.
Kod blokları
- Kısa tutun. Kod örneğindeki tüm gereksiz 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ınlaştırma yerine satır içi kod stili kullanın.
- Evet:
bazel help <command>:<command>ile ilgili yardım ve seçenekler yazdırılır. - Hayır: bazel help command: "command" için yardım ve seçenekleri yazdırır.
- Evet: