Bazel'in dokümanlarına katkıda bulunduğunuz için teşekkür ederiz. Bu, başlangıç için hızlı bir belgeleme stil kılavuzu işlevi görür. Bu kılavuzda yanıtlanmayan tüm stil soruları için Google geliştirici belgeleri stil kılavuzunu takip edin.
İlkeleri tanımlama
Bazel dokümanları şu ilkeleri uygulamalıdır:
- Kısa. Mümkün olduğunca az kelime kullanın.
- Açık. Sade bir dil kullanın. Beşinci sınıf okuma seviyesi için jargon kullanmadan yazın.
- Tutarlı. Dokümanlar genelinde tekrarlanan kavramlar için aynı kelimeleri veya ifadeleri kullanın.
- Doğru. Zamana dayalı bilgilerden ve gelecek vadeden sözlerden kaçınarak içeriğin mümkün olduğu kadar uzun süre doğru kaldığı bir şekilde yazın.
Yazım
Bu bölümde, yazımla ilgili temel ipuçları yer alı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.)
Başlıkları mümkün olduğunca kısa tutun. Bu sayede, sarmalamaya gerek olmadan Kullanım Şartları'na uyum sağlarlar.
- 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ı Kurma
Başlıkları göreve dayalı veya eyleme geçirilebilir hale getirmeye çalışın. Başlıklar, kavramsalsa anlayışa dayalı olabilir ancak kullanıcı ne yaptığına dikkat edin.
- Evet: Grafik sırası korunuyor
- Hayır: Grafik düzeninin korunması hakkında
Adlar
Özel isimlerin ilk harfini büyük yazın (ör. Bazel ve Starlark).
- Evet: Derlemenin sonunda Bazel, istenen hedefleri yazdırır.
- Hayır: Derlemenin sonunda Bazel, istenen hedefleri yazdırır.
Tutarlı olun. Mevcut kavramlar için yeni adlar girmeyin. Uygun durumlarda, Sözlük'te tanımlanan terimi kullanın.
- Örneğin, bir terminalde komut yayınlama hakkında yazıyorsanız sayfada hem terminal hem de komut satırı kullanmayın.
Sayfa kapsamı
Her sayfanın bir amacı olmalıdır ve bu amaç başta tanımlanmalıdır. Bu, okuyucuların ihtiyaç duydukları şeyi daha hızlı bulmalarına yardımcı olur.
- Evet: Bu sayfa, Windows'a Bazel'ın nasıl yükleneceğini ele alır.
- Hayır: (Giriş cümlesi yoktur.)
Sayfanın sonunda, okuyucuya bir sonraki adımda ne yapması gerektiğini söyleyin. Net bir işlemin olmadığı sayfalar için benzer kavramlara, örneklere veya başka keşif yollarının bağlantılarını ekleyebilirsiniz.
Konu
Bazel belgelerinde hedef kitlenin öncelikli olarak kullanıcılar, yani yazılımlarını oluşturmak için Bazel kullanan kişiler olması gerekir.
Okuyucunuza “siz” şeklinde hitap edin. (Herhangi bir nedenle "siz" ifadesini kullanamıyorsanız cinsiyetsiz 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: 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 sorumlular, katkıda bulunanlar, göçmenler veya diğer roller yer alabilir.
"Biz" ifadelerini kullanmaktan kaçının. Kullanıcı dokümanlarında yazar yoktur. Kullanıcılara neyin mümkün olduğunu söyleyin.
- Evet: Bazel geliştikçe uyumluluğu sağlamak için kod tabanınızı güncellemeniz gerekir.
- Hayır: Bazel gelişmektedir. Zaman zaman uyumsuz ve Bazel kullanıcılarının bazı değişiklikler yapması gereken değişiklikler için Bazel'de değişiklikler yapacağız.
Geçici
Mümkün olduğu durumlarda, belirli tarihlere (2022 2022'nin 2. çeyreği) atıfta bulunmak ya da "şimdi", "şu anda" veya "yakında" gibi ifadelerden kaçının. Bunlar hızla eskir ve gelecekteki bir projeksiyonsa yanlış olabilir. Bunun yerine, "Bazel X.x ve sonraki sürümler <feature> desteği veya bir GitHub sorunu bağlantısı" 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, muhtemelen Ekim 2017'de uzaktan önbelleğe alma özelliğini destekleyecektir.
Gergin
Şimdiki zamanı kullanın. Netlik sağlamak 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 bir hata bildirir.
Mümkün olduğunda, pasif ses yerine (öznenin bir nesneye hareket ettiği yerlerde) etken çatı kullanın. Genellikle aktif üslup kimin sorumlu olduğunu gösterdiği için cümleleri netleştirir. Etkin ses kullanmak netliği azaltıyorsa pasif ses kullanın.
- Evet: Bazel X'i başlatır ve Y'yi derlemek için çıkışı kullanır.
- Hayır: X Bazel tarafından başlatılır ve ardından Y çıktıyla birlikte 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: İyi bir kural grubu nedir?
Fazla resmi dil kullanmaktan kaçının. Teknolojiyi merak eden ancak ayrıntılarını bilmeyen bir kişiye kavramı açıklıyormuş gibi yazın.
Biçimlendirme
Dosya türü
Okunabilirlik için satırları 80 karakterde 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, dokümanları taramayı kolaylaştırır ve ekran okuyucular için daha iyidir.
- Evet: Daha fazla bilgi için [Bazel'i Yükleme] konusuna bakın.
- Hayır: Daha fazla bilgi için [here] sayfasını inceleyin.
Cümleyi mümkünse bağlantıyla bitirin.
- Evet: Daha fazla bilgi için [link] bölümüne bakın.
- Hayır: Daha fazla bilgi için [link] adresine bakın.
Listeler
- Bir görevin adımlarla nasıl tamamlanacağını açıklamak için sıralı bir liste kullanın
- Göreve dayalı olmayan öğeleri listelemek için sıralanmamış bir liste kullanın. (Sıralamada alfabetik, önem vb. gibi bir sıralama olması gerekir)
- Paralel yapıyla yazın. Örneğin:
- Tüm liste öğeleri cümlelerini oluşturun.
- Zamanları aynı olan fiillerle başlayın.
- Uygulanacak 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çları kullanın. Markdown'da, açılı ayraçlardan ters eğik çizgi kullanarak çıkış yapın:
\<example\>.- Evet:
bazel help <command>:<command>için yazdırma yardımı ve seçenekleri - Hayır: bazel yardım komutu: "Komut" için yardımı ve seçenekleri yazdırır
- Evet:
Özellikle karmaşık kod örnekleri söz konusu olduğunda bağlam açısından anlamlı olan yer tutucular kullanın.
İçindekiler
Site tarafından desteklenen, otomatik olarak oluşturulan TOC'yi kullanın. Manuel TOC eklemeyin.
Kod
Kod örnekleri, geliştiricilerin en iyi arkadaşlarıdır. Bunları nasıl yazacağınızı muhtemelen biliyorsunuzdur ama size birkaç ipucu vereyim.
Küçük bir kod snippet'ine referans veriyorsanız bunu bir cümleye yerleştirebilirsiniz. Okuyucunun kodu kullanmasını (ör. bir komut kopyalama) istiyorsanız kod bloğu kullanın.
Kod blokları
- Fragmanı kısa tutun. Kod örneğinden 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ı yerine satır içi kod stilini kullanın.
- Evet:
bazel help <command>:<command>için yazdırma yardımı ve seçenekleri - Hayır: bazel yardım komutu: "Komut" için yardımı ve seçenekleri yazdırır
- Evet: