Terima kasih telah berkontribusi pada dokumentasi Bazel. Hal ini berfungsi sebagai panduan gaya dokumentasi untuk membantu Anda memulai. Untuk pertanyaan gaya yang tidak dijawab oleh panduan ini, ikuti Panduan gaya dokumentasi developer Google.
Mendefinisikan prinsip-prinsip
Dokumen Bazel harus menjunjung prinsip berikut:
- Singkat. Gunakan kata sesedikit mungkin.
- Hapus. Gunakan bahasa sederhana. Tulis tanpa jargon untuk kelas lima tingkat kemampuan membaca.
- Konsisten. Gunakan kata atau frasa yang sama untuk konsep berulang di seluruh dokumentasi.
- Benar. Tulis dengan cara yang kontennya tetap benar selama mungkin dengan menghindari informasi berbasis waktu dan janji untuk masa depan.
Penulisan
Bagian ini berisi tips penulisan dasar.
Judul
- Judul tingkat halaman dimulai dari H2. (Judul H1 digunakan sebagai judul halaman.)
Buat {i>header<i} sesingkat mungkin. Dengan cara ini, daftar tersebut sesuai dengan daftar isi tanpa wrapping.
- Ya: Izin
- Tidak: Catatan singkat tentang izin
Gunakan kapitalisasi kalimat untuk judul
- Ya: Siapkan ruang kerja Anda
- Tidak: Siapkan Workspace Anda
Cobalah untuk membuat judul berdasarkan tugas atau dapat ditindaklanjuti. Jika {i>heading<i} bersifat konseptual, hal itu mungkin didasarkan pada pemahaman, tetapi tulislah apa yang dilakukan pengguna.
- Ya: Mempertahankan urutan grafik
- Tidak: Untuk mempertahankan urutan grafik
Nama
Gunakan huruf besar untuk kata benda khusus, seperti Bazel dan Starlark.
- Ya: Di akhir build, Bazel akan mencetak target yang diminta.
- Tidak: Di akhir build, bazel akan mencetak target yang diminta.
Jaga agar tetap konsisten. Jangan memperkenalkan nama baru untuk konsep yang sudah ada. Lokasi berlaku, gunakan istilah yang didefinisikan dalam Glosarium.
- Misalnya, jika Anda menulis tentang mengeluarkan perintah pada terminal, jangan gunakan terminal dan baris perintah pada laman.
Cakupan halaman
Setiap halaman harus memiliki satu tujuan dan didefinisikan di memulai. Hal ini membantu pembaca menemukan apa yang mereka butuhkan dengan lebih cepat.
- Ya: Halaman ini membahas cara menginstal Bazel di Windows.
- Tidak: (Tidak ada kalimat pengantar.)
Di akhir halaman, beri tahu pembaca apa yang harus dilakukan selanjutnya. Untuk halaman yang tidak ada tindakan yang jelas, Anda dapat menyertakan tautan ke konsep serupa, contoh, atau cara lain untuk melakukan eksplorasi.
Subject
Dalam dokumentasi Bazel, audiens utamanya haruslah pengguna—orang-orang yang menggunakan Bazel untuk membangun perangkat lunak mereka.
Panggil pembaca sebagai "Anda". (Jika karena alasan tertentu Anda tidak dapat menggunakan "Anda", menggunakan bahasa yang netral gender, seperti bahasa mereka.)
- Ya: Untuk membuat kode Java menggunakan Bazel, Anda harus menginstal JDK.
- MAYBE: Agar pengguna dapat membuat kode Java dengan Bazel, mereka harus menginstal JDK.
- Tidak: Agar pengguna dapat membuat kode Java dengan Bazel, dia harus memasang JDK.
Jika audiens Anda BUKAN pengguna Bazel umum, tentukan audiens di awal halaman atau di bagian tersebut. Audiens lainnya dapat mencakup pengelola, kontributor, migrasi, atau peran lainnya.
Hindari kata "we". Dalam dokumen pengguna, tidak ada penulis; beri tahu orang-orang apa yang sebaik mungkin.
- Ya: Seiring perkembangan Bazel, Anda harus mengupdate code base untuk mempertahankan kompatibilitas mundur.
- Tidak: Bazel terus berkembang, dan kami akan melakukan perubahan pada Bazel dengan kali akan tidak kompatibel dan memerlukan beberapa perubahan dari pengguna Bazel.
Sementara
Jika memungkinkan, hindari istilah yang mengarahkan segala sesuatunya pada waktu yang tepat, seperti mereferensikan tanggal tertentu (Kuartal 2 2022) atau mengatakan "sekarang", "saat ini", atau "segera". Ini termasuk cepat basi dan bisa salah jika itu adalah proyeksi di masa depan. Sebagai gantinya, menentukan tingkat versi, seperti "Bazel X.x dan versi dukungan <feature> atau link masalah GitHub.
- Ya: Bazel 0.10.0 atau yang lebih baru mendukung pembuatan cache jarak jauh.
- Tidak: Bazel akan segera mendukung remote penyimpanan dalam cache, kemungkinan pada Oktober 2017.
Tense
Menggunakan present tense. Hindari ketegangan masa lalu atau masa depan kecuali jika benar-benar diperlukan agar lebih jelas.
- Ya: Bazel mengeluarkan error saat menemukan dependensi yang tidak sesuai dengan aturan ini.
- Tidak: Jika Bazel menemukan dependensi yang tidak sesuai dengan aturan ini, Bazel akan mengeluarkan kesalahan.
Jika memungkinkan, gunakan kalimat aktif (saat subjek bertindak pada suatu objek) bukan kalimat pasif (ketika suatu objek ditindaklanjuti oleh subjek). Umumnya, kalimat aktif memperjelas kalimat karena menunjukkan siapa yang bertanggung jawab. Jika menggunakan kalimat aktif mengurangi kejelasan, menggunakan kalimat pasif.
- Ya: Bazel memulai X dan menggunakan output untuk membangun Y.
- No: X dimulai oleh Bazel dan kemudian setelah itu Y akan dibangun dengan {i>output<i}.
Nuansa
Tulis dengan nada bisnis yang ramah.
Hindari bahasa sehari-hari. Akan lebih sulit untuk menerjemahkan frasa yang khusus untuk bahasa Inggris.
- Ya: Kumpulan aturan yang baik
- Tidak: Jadi, seperti apa kumpulan aturan yang baik itu?
Hindari bahasa yang terlalu formal. Tulis seolah-olah Anda sedang menjelaskan konsep kepada seseorang yang ingin tahu tentang teknologi, tetapi tidak tahu detailnya.
Pemformatan
Jenis file
Agar mudah dibaca, kemas baris pada 80 karakter. Link panjang atau cuplikan kode mungkin lebih lama, tetapi harus dimulai pada baris baru. Contoh:
Link
Gunakan teks link deskriptif alih-alih "di sini" atau "di bawah". Praktik ini mempermudah pemindaian dokumen dan lebih baik untuk {i>screen reader<i}.
- Ya: Untuk mengetahui detail selengkapnya, lihat [Menginstal Bazel].
- Tidak: Untuk detail selengkapnya, lihat [di sini].
Akhiri kalimat dengan link, jika memungkinkan.
- Ya: Untuk mengetahui detail selengkapnya, lihat [link].
- Tidak: Lihat [link] untuk informasi selengkapnya.
Daftar
- Menggunakan daftar yang diurutkan untuk menjelaskan cara menyelesaikan tugas dengan langkah-langkah
- Gunakan daftar yang tidak diurutkan untuk mencantumkan hal-hal yang tidak berbasis tugas. (Seharusnya ada masih dalam urutan yang sama, seperti menurut abjad, tingkat kepentingan, dll.)
- Menulis dengan struktur paralel. Misalnya:
- Membuat semua kalimat item daftar.
- Mulailah dengan kata kerja yang memiliki bentuk waktu yang sama.
- Gunakan daftar yang diurutkan jika ada langkah-langkah yang harus diikuti.
Placeholder
Gunakan tanda kurung sudut untuk menunjukkan variabel yang harus diubah pengguna. Di Markdown, hilangkan tanda kurung sudut dengan garis miring kembali:
\<example\>.- Ya:
bazel help <command>: Cetakan bantuan dan opsi untuk<command> - No: perintah bantuan bazel: Mencetak bantuan dan opsi untuk "{i>command<i}"
- Ya:
Terutama untuk contoh kode yang rumit, gunakan placeholder yang masuk akal sesuai konteks.
Daftar isi
Gunakan TOC yang dibuat otomatis yang didukung oleh situs. Jangan tambahkan TOC manual.
Kode
Contoh kode adalah sahabat. Anda mungkin tahu cara menulisnya tapi berikut ini beberapa tip.
Jika merujuk pada cuplikan kode berukuran kecil, Anda dapat menyematkannya dalam sebuah kalimat. Jika Anda ingin pembaca menggunakan kode tersebut, seperti menyalin perintah, gunakan kode diblokir.
Blok kode
- Buat cuplikan dengan durasi singkat. Menghilangkan semua teks yang berlebihan atau tidak perlu dari kode contoh.
- Dalam Markdown, tentukan jenis blok kode dengan menambahkan bahasa sampel.
```shell
...
- Pisahkan perintah dan output ke dalam blok kode yang berbeda.
Pemformatan kode sebaris
- Gunakan gaya kode untuk nama file, direktori, jalur, dan bit kecil kode.
- Gunakan gaya visual kode inline, bukan miring, "tanda kutip", atau tebal.
- Ya:
bazel help <command>: Cetakan bantuan dan opsi untuk<command> - No: perintah bantuan bazel: Mencetak bantuan dan opsi untuk "{i>command<i}"
- Ya: