Bazel'in dokümanlarına katkıda bulunduğunuz için teşekkür ederiz. Bu şekilde sık sık erişilen tüm dosyalarınıza belge stil kılavuzuna göz atın. Stil soruları için daha fazla bilgi için Google geliştirici belgeleri stil kılavuzu.
İ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 için jargon kullanmadan yazmak okuma seviyesi.
- Tutarlı olun. Tekrarlanan kavramlar için aynı kelimeleri veya kelime öbeklerini kullanın bazı ipuçları vereceğim.
- Doğru. İçerikler uzun süre boyunca doğru kalacak şekilde yazın. geleceğe yönelik vaatlerden kaçınarak mümkün olur.
Yazma
Bu bölümde, yazmayla ilgili temel ipuçları yer almaktadır.
Başlıklar
- 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, Topluluk Kuralları'na uyarlar. sarmalamadan.
- 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 anlayışa dayalı olabilir ama kullanıcının ne yaptığına 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. Konum Google Ads şartlar ve koşullarında Sözlük.
- Örneğin, bir web sitesinde komut verme hakkında yazıyorsanız terminal, sayfada hem terminal hem de komut satırını kullanmayın.
Sayfa kapsamı
Her sayfanın tek bir amacı olmalıdır ve bu amaç, başlar. 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. Sayfalar için net bir işlem olmadığından, benzer kavramların bağlantılarını ekleyebilirsiniz. veya başka keşfetme yolları bulabilir.
Konu
Bazel belgelerinde hedef kitle olarak öncelikle kullanıcılar, Bazel'ın yazılımlarını geliştirmesini istedi.
Okuyucunuza "siz" hitap etmek. (Herhangi bir nedenle "siz" ifadesini kullanamıyorsanız, cinsiyet içermeyen bir dil kullanmalıdır.)
- Evet: Bazel kullanarak Java kodu oluşturmak için bir JDK yüklemelisiniz.
- 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 Java kodu derlemesi için bir JDK yüklemesi gerekir.
Kitleniz genel Bazel kullanıcıları DEĞİLSE kitleyi bir metin ekleyin. Diğer kitleler şunları içerebilir: devam edenler, katkıda bulunanlar, taşıyıcılar veya diğer rollerdir.
"Biz" demekten kaçının. Kullanıcı dokümanlarında yazar yoktur; insanlara yapmasını sağlar.
- Evet: Bazel geliştikçe kod tabanınızı güncelleyerek uyumluluk.
- Hayır: Bazel gelişiyor. Biz de Bazel'de şu tarihte değişiklikler yapacağız: zamanları uyumsuz olacak ve Bazel kullanıcılarının bazı değişiklikleri yapmasını gerektirecektir.
Geçici
Mümkün olduğu durumlarda, referanslar gibi, zamana ayak uyduracak terimler kullanmaktan kaçının. belirli tarihler (2022 2. Çeyrek) veya "şimdi", "şu anda" veya "yakında" şeklinde ifade edilebilir. Bunlar hazır hızlı eskiyebilir ve gelecekteki bir projeksiyonsa yanlış olabilir. Bunun yerine bunun yerine "Bazel X.x ve sonraki sürümleri destekler" gibi bir sürüm düzeyi belirtin <feature> veya GitHub sorun bağlantısını kullanın.
- Evet: Bazel 0.10.0 veya sonraki sürümler destekler uzaktan önbelleğe alma.
- Hayır: Bazel yakında uzaktan kumanda özelliğini destekleyecek önbelleğine alma, büyük ihtimalle Ekim 2017'de.
Gergin
Şimdiki zaman kullanın. Kesinlikle gerekli olmadığı sürece geçmiş veya gelecek zamanları kullanmaktan kaçının emin olmanız gerekir.
- Evet: Bazel, aşağıdaki işlemleri yaparken hata mesajı verir: bu kurala uymayan bağımlılıkları bulur.
- Hayır: Bazel bu kurala uymuyorsa Bazel bir hata verir.
Mümkün olduğunda pasif ses (bir öznenin bir nesneye hareket etmesi). Genellikle, etken çatı, kimin sorumlu olduğunu gösterdiği için cümleleri daha anlaşılır hale getirir. Eğer etkin ses kullanmak netliği azaltacaktır, edilgen çatı kullanın.
- Evet: Bazel, X'i başlatır ve çıktı olarak işaretleyeceksiniz.
- Hayır: X, Bazel tarafından başlatılır ve ardından daha sonra, Y ise çıktıyla oluşturulur.
Ton
İş dostu bir üslup kullanarak yazın.
Konuşma dili kullanmaktan kaçının. Türkçe gibi ifadelere cevap vermek tercih edebilirsiniz.
- Evet: İyi kural kümeleri
- Hayır: Peki, iyi kural kümesi nedir?
Fazla resmi bir dil kullanmaktan kaçının. Konuyu açıklıyormuş gibi yazın merak eden ama ayrıntıları bilmeyen kişilere göstermek isteyebilir.
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 olabilir, ancak yeni bir satırda başlamalıdır. Örneğin:
Bağlantılar
"Burada" yerine açıklayıcı bağlantı metni kullanın veya "aşağıda" gibi görünebilir. Bu uygulama doküman taramayı kolaylaştırır ve ekran okuyucular için daha iyidir.
- 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. ( (ör. alfabetik, önem vb.) bir sıralama sıralaması olmalıdır.)
- Paralel yapıyla yazma. Örnek:
- 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>: Baskılar<command>için yardım ve seçenekler - Hayır: bazel yardım komutu: Yazdırma yardımı ve "komut" seçenekleri
- Evet:
Özellikle karmaşık kod örnekleri için, bağlamında inceleyelim.
İçindekiler
Site tarafından desteklenen otomatik olarak oluşturulmuş TOC'yi kullanın. Manuel TOC eklemeyin.
Kod
Kod örnekleri, en iyi arkadaşlar. Muhtemelen bunların nasıl yazılacağını biliyorsunuzdur. ama şimdi size birkaç ipucu vereceğim.
Küçük bir kod snippet'inden bahsediyorsanız kodu cümleye yerleştirebilirsiniz. Okuyucunun kodu kullanmasını istiyorsanız (ör. bir komut kopyalamak) engelleyebilirsiniz.
Kod blokları
- Kısa tutun. Gereksiz ve gereksiz tüm metinleri koddan kaldırın örneklem.
- 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 işaretleri" yerine satır içi kod stilini kullanın. veya kalın karakterler ekleyebilirsiniz.
- Evet:
bazel help <command>: Baskılar<command>için yardım ve seçenekler - Hayır: bazel yardım komutu: Yazdırma yardımı ve "komut" seçenekleri
- Evet: