Panduan gaya dokumen Bazel

Terima kasih telah berkontribusi pada dokumentasi Bazel. Dokumen ini berfungsi sebagai panduan gaya dokumentasi singkat untuk membantu Anda memulai. Untuk pertanyaan gaya yang tidak dijawab oleh panduan ini, ikuti panduan gaya dokumentasi developer Google.

Menentukan prinsip

Dokumen Bazel harus mematuhi prinsip berikut:

• Ringkas. Gunakan sesedikit mungkin kata.
• Jelas. Gunakan bahasa yang sederhana. Tulis tanpa jargon untuk tingkat membaca kelas lima.
• Konsisten. Gunakan kata atau frasa yang sama untuk konsep yang berulang di seluruh dokumen.
• Benar. Tulis dengan cara yang membuat konten tetap benar selama mungkin dengan menghindari informasi berbasis waktu dan janji untuk masa mendatang.

Menulis

Bagian ini berisi tips penulisan dasar.

Judul

• Judul tingkat halaman dimulai dari H2. (Judul H1 digunakan sebagai judul halaman.)

• Buat header sesingkat mungkin. Dengan begitu, header akan sesuai dengan daftar isi tanpa di-wrap.

  • Ya: Izin
  • Tidak: Catatan singkat tentang izin

• Gunakan kapitalisasi kalimat untuk judul

  • Ya: Menyiapkan ruang kerja
  • Tidak: Menyiapkan Ruang Kerja

• Coba buat judul berbasis tugas atau dapat ditindaklanjuti. Jika judul bersifat konseptual, judul tersebut mungkin didasarkan pada pemahaman, tetapi tulis sesuai dengan tindakan pengguna.

  • Ya: Mempertahankan urutan grafik
  • Tidak: Tentang mempertahankan urutan grafik

Nama

• Kapitalisasi kata benda yang tepat, seperti Bazel dan Starlark.

  • Ya: Di akhir build, Bazel mencetak target yang diminta.
  • Tidak: Di akhir build, bazel mencetak target yang diminta.

• Tetap konsisten. Jangan memperkenalkan nama baru untuk konsep yang ada. Jika berlaku, gunakan istilah yang ditentukan dalam Glosarium.

  • Misalnya, jika Anda menulis tentang mengeluarkan perintah di terminal, jangan gunakan terminal dan command line di halaman.

Cakupan halaman

• Setiap halaman harus memiliki satu tujuan dan tujuan tersebut harus ditentukan di awal. Hal ini membantu pembaca menemukan hal 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 memiliki tindakan yang jelas, Anda dapat menyertakan link ke konsep, contoh, atau cara lain yang serupa untuk eksplorasi.

Subjek

Dalam dokumentasi Bazel, audiens utamanya adalah pengguna—orang yang menggunakan Bazel untuk membuat software mereka.

• Sapa pembaca Anda sebagai "Anda". (Jika karena alasan tertentu Anda tidak dapat menggunakan "Anda", gunakan bahasa yang netral gender, seperti mereka.)

  • Ya: Untuk membuat kode Java menggunakan Bazel, Anda harus menginstal JDK.
  • MUNGKIN: Agar pengguna dapat membuat kode Java dengan Bazel, mereka harus menginstal JDK.
  • Tidak: Agar pengguna dapat membuat kode Java dengan Bazel, dia harus menginstal JDK.

• Jika audiens Anda BUKAN pengguna Bazel umum, tentukan audiens di awal halaman atau di bagian tersebut. Audiens lainnya dapat mencakup pengelola, kontributor, migrator, atau peran lainnya.

• Hindari "kami". Dalam dokumen pengguna, tidak ada penulis; cukup beri tahu orang-orang tentang apa yang mungkin dilakukan.

  • Ya: Seiring perkembangan Bazel, Anda harus memperbarui basis kode untuk mempertahankan kompatibilitas.
  • Tidak: Bazel terus berkembang, dan kami akan melakukan perubahan pada Bazel yang terkadang tidak kompatibel dan memerlukan beberapa perubahan dari pengguna Bazel.

Temporal

Jika memungkinkan, hindari istilah yang mengorientasikan hal-hal dalam waktu, seperti mereferensikan tanggal tertentu (Q2 2022) atau mengatakan "sekarang", "saat ini", atau "segera". Istilah ini akan cepat usang dan mungkin salah jika merupakan proyeksi masa depan. Sebagai gantinya, tentukan tingkat versi, seperti "Bazel X.x dan yang lebih tinggi mendukung <feature> atau link masalah GitHub.

• Ya: Bazel 0.10.0 atau yang lebih baru mendukung caching jarak jauh.
• Tidak: Bazel akan segera mendukung caching jarak jauh, kemungkinan pada Oktober 2017.

Tense

• Gunakan present tense. Hindari past tense atau future tense kecuali benar-benar diperlukan untuk kejelasan.

  • Ya: Bazel menampilkan error saat menemukan dependensi yang tidak sesuai dengan aturan ini.
  • Tidak: Jika Bazel menemukan dependensi yang tidak sesuai dengan aturan ini, Bazel akan menampilkan error.

• Jika memungkinkan, gunakan kalimat aktif (dengan subjek yang bertindak atas objek) bukan kalimat pasif (dengan objek yang ditindaklanjuti oleh subjek). Umumnya, kalimat aktif membuat kalimat lebih jelas karena menunjukkan siapa yang bertanggung jawab. Jika penggunaan kalimat aktif mengurangi kejelasan, gunakan kalimat pasif.

  • Ya: Bazel memulai X dan menggunakan output untuk membuat Y.
  • Tidak: X dimulai oleh Bazel dan kemudian Y akan dibuat dengan output.

Nada

Tulis dengan nada yang ramah bisnis.

• Hindari bahasa sehari-hari. Frasa yang khusus untuk bahasa Inggris lebih sulit diterjemahkan.

  • Ya: Ruleset yang baik
  • Tidak: Jadi, apa itu ruleset yang baik?

• Hindari bahasa yang terlalu formal. Tulis seolah-olah Anda menjelaskan konsep tersebut kepada seseorang yang penasaran dengan teknologi, tetapi tidak mengetahui detailnya.

Pemformatan

Jenis file

Untuk keterbacaan, gabungkan baris pada 80 karakter. Link atau cuplikan kode yang panjang mungkin lebih panjang, tetapi harus dimulai pada baris baru. Contoh:

Link

• Gunakan teks link deskriptif, bukan "di sini" atau "di bawah". Praktik ini memudahkan pemindaian dokumen dan lebih baik untuk pembaca layar.

  • Ya: Untuk mengetahui detail selengkapnya, lihat [Menginstal Bazel].
  • Tidak: Untuk mengetahui detail selengkapnya, lihat [di sini].

• Akhiri kalimat dengan link, jika memungkinkan.

  • Ya: Untuk mengetahui detail selengkapnya, lihat [link].
  • Tidak: Lihat [link] untuk mengetahui informasi selengkapnya.

Daftar

• Gunakan daftar berurutan untuk menjelaskan cara menyelesaikan tugas dengan langkah-langkah
• Gunakan daftar tidak berurutan untuk mencantumkan hal-hal yang tidak berbasis tugas. (Harus tetap ada urutan, seperti abjad, kepentingan, dll.)
• Tulis dengan struktur paralel. Contoh:
  1. Buat semua item daftar menjadi kalimat.
  2. Mulai dengan kata kerja yang memiliki tense yang sama.
  3. Gunakan daftar berurutan jika ada langkah-langkah yang harus diikuti.

Placeholder

• Gunakan tanda kurung sudut untuk menunjukkan variabel yang harus diubah pengguna. Di Markdown, escape tanda kurung sudut dengan garis miring terbalik: \<example\>.

  • Ya: bazel help <command>: Mencetak bantuan dan opsi untuk <command>
  • Tidak: bazel help command: Mencetak bantuan dan opsi untuk "command"

• Terutama untuk contoh kode yang rumit, gunakan placeholder yang sesuai dalam konteks.

Daftar isi

Gunakan daftar isi yang dibuat otomatis dan didukung oleh situs. Jangan tambahkan daftar isi manual.

Kode

Contoh kode adalah teman terbaik developer. Anda mungkin sudah tahu cara menulisnya, tetapi berikut beberapa tips.

Jika mereferensikan cuplikan kode kecil, Anda dapat menyematkannya dalam kalimat. Jika Anda ingin pembaca menggunakan kode tersebut, seperti menyalin perintah, gunakan blok kode.

Blok kode

• Buat cuplikan dengan durasi singkat. Hapus semua teks yang berlebihan atau tidak perlu dari contoh kode.
• Di Markdown, tentukan jenis blok kode dengan menambahkan bahasa contoh.

```shell
...

• Pisahkan perintah dan output ke dalam blok kode yang berbeda.

Pemformatan kode inline

• Gunakan gaya kode untuk nama file, direktori, jalur, dan kode kecil.
• Gunakan gaya kode inline, bukan cetak miring, "tanda kutip", atau cetak tebal.
  • Ya: bazel help <command>: Mencetak bantuan dan opsi untuk <command>
  • Tidak: bazel help command: Mencetak bantuan dan opsi untuk "command"