Panduan gaya dokumen Bazel

Laporkan masalah Lihat sumber Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

Menentukan prinsip

Dokumen Bazel harus menjunjung tinggi prinsip-prinsip berikut:

  • Singkat. Gunakan kata sesedikit mungkin.
  • 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 depan.

Penulisan

Bagian ini berisi tips menulis dasar.

Judul

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

  • Buat header yang sesingkat mungkin. Dengan cara ini, judul tersebut akan sesuai dengan TOC tanpa digabungkan.

    • Ya: Izin
    • Tidak: Catatan singkat tentang izin

  • Menggunakan kapitalisasi kalimat untuk judul

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

  • Coba buat judul berbasis tugas atau yang dapat ditindaklanjuti. Jika judul bersifat konseptual, judul tersebut mungkin didasarkan pada pemahaman, tetapi tuliskan apa yang dilakukan pengguna.

    • Ya: Mempertahankan urutan grafik
    • Tidak: Pada pelestarian urutan grafik

Nama

  • Gunakan huruf besar untuk kata benda, seperti Bazel dan Starlark.

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

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

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

Cakupan halaman

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

Subjek

Dalam dokumentasi Bazel, audiens utamanya harus berupa pengguna—orang yang menggunakan Bazel untuk mem-build software mereka.

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

    • Ya: Untuk mem-build kode Java menggunakan Bazel, Anda harus menginstal JDK.
    • MUNGKIN: Agar dapat mem-build kode Java dengan Bazel, pengguna harus menginstal JDK.
    • Tidak: Agar pengguna dapat mem-build kode Java dengan Bazel, ia harus menginstal JDK.

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

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

    • Ya: Seiring berkembangnya Bazel, Anda harus mengupdate codebase untuk mempertahankan kompatibilitas.
    • Tidak: Bazel terus berkembang, dan kami akan membuat perubahan pada Bazel yang terkadang tidak kompatibel dan memerlukan beberapa perubahan dari pengguna Bazel.

Temporal

Jika memungkinkan, hindari istilah yang mengorientasikan sesuatu dalam waktu, seperti merujuk pada tanggal tertentu (Kuartal 2 2022) atau mengatakan "sekarang", "saat ini", atau "segera". Data ini cepat menjadi usang dan mungkin salah jika merupakan proyeksi masa mendatang. Sebagai gantinya, tentukan level 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 cache jarak jauh.
  • Tidak: Bazel akan segera mendukung cache jarak jauh, kemungkinan pada Oktober 2017.

Tense

  • Gunakan bentuk kata kerja present tense. Hindari bentuk lampau atau mendatang kecuali benar-benar diperlukan untuk kejelasan.

    • Ya: Bazel akan 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 (saat subjek bertindak terhadap objek), bukan kalimat pasif (saat objek ditindaklanjuti oleh subjek). Umumnya, kalimat aktif membuat kalimat lebih jelas karena menunjukkan siapa yang bertanggung jawab. Jika menggunakan kalimat aktif mengurangi kejelasan, gunakan kalimat pasif.

    • Ya: Bazel memulai X dan menggunakan output untuk mem-build Y.
    • Tidak: X dimulai oleh Bazel, lalu setelah itu Y akan di-build dengan output.

Nuansa

Tulis dengan nada yang bersahabat dengan bisnis.

  • Hindari bahasa sehari-hari. Lebih sulit untuk menerjemahkan frasa yang khusus untuk bahasa Inggris.

    • Ya: Kumpulan aturan yang baik
    • Tidak: Jadi, apa yang dimaksud dengan kumpulan aturan yang baik?

  • Hindari bahasa yang terlalu formal. Tulis seolah-olah Anda menjelaskan konsep kepada seseorang yang ingin tahu tentang teknologi, tetapi tidak mengetahui detailnya.

Pemformatan

Jenis file

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

  • 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

  • Menggunakan daftar urut untuk menjelaskan cara menyelesaikan tugas dengan langkah-langkah
  • Gunakan daftar acak untuk mencantumkan hal-hal yang tidak berbasis tugas. (Harus masih ada urutan, seperti abjad, tingkat kepentingan, dll.)
  • Tulis dengan struktur paralel. Misalnya:
    1. Buat semua item daftar menjadi kalimat.
    2. Mulailah dengan kata kerja yang memiliki bentuk waktu yang sama.
    3. Gunakan daftar urut jika ada langkah-langkah yang harus diikuti.

Placeholder

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

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

  • Khusus untuk contoh kode yang rumit, gunakan placeholder yang masuk akal dalam konteks.

Daftar isi

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

Kode

Contoh kode adalah sahabat 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, 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 potongan kecil kode.
  • Gunakan gaya kode inline, bukan miring, "tanda kutip", atau bolding.
    • Ya: bazel help <command>: Mencetak bantuan dan opsi untuk <command>
    • Tidak: bazel help command: Mencetak bantuan dan opsi untuk "command"