Panduan gaya dokumen Bazel

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

Menentukan prinsip

Dokumen Bazel harus menjunjung tinggi prinsip-prinsip berikut:

  • Ringkas. Gunakan kata sesedikit mungkin.
  • Hapus. Gunakan bahasa yang sederhana. Tulis tanpa jargon untuk tingkat kemampuan baca 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 dan janji berbasis waktu untuk masa depan.

Menulis

Bagian ini berisi tips menulis dasar.

Judul

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

  • Buat header sesingkat mungkin. Dengan cara ini, mereka akan cocok di daftar isi tanpa di-wrap.

    • Ya: Izin
    • Tidak: Catatan singkat tentang izin

  • Menggunakan kapitalisasi kalimat untuk judul

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

  • 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

  • Gunakan huruf kapital untuk kata benda khusus, 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 sudah ada. Jika sesuai, 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 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 tindakan yang harus dilakukan selanjutnya. Untuk halaman yang tidak ada tindakan yang jelas, Anda dapat menyertakan link ke konsep serupa, contoh, atau cara lain untuk eksplorasi.

Subjek

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

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

    • Ya: Untuk membuat kode Java menggunakan Bazel, Anda harus menginstal JDK.
    • MUNGKIN: Agar dapat membuat kode Java dengan Bazel, pengguna 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. Audiens lain dapat mencakup pemelihara, kontributor, migrator, atau peran lainnya.

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

    • Ya: Seiring berkembangnya Bazel, Anda harus mengupdate code base 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 mengarahkan sesuatu dalam waktu, seperti merujuk pada tanggal tertentu (Q2 2022) atau mengatakan "sekarang", "saat ini", atau "segera". Data ini cepat menjadi tidak valid dan bisa 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 penyimpanan cache jarak jauh.
  • Tidak: Bazel akan segera mendukung penyimpanan cache jarak jauh, kemungkinan pada Oktober 2017.

Tense

  • Gunakan kala kini. Hindari penggunaan bentuk lampau atau bentuk masa depan kecuali benar-benar diperlukan untuk kejelasan.

    • Ya: Bazel akan 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 error.

  • Jika memungkinkan, gunakan kalimat aktif (subjek bertindak atas objek), bukan kalimat pasif (objek bertindak atas 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 membangun Y.
    • Tidak: X dimulai oleh Bazel, lalu setelah itu Y akan dibangun dengan output.

Nada

Tulis dengan gaya bahasa yang sesuai untuk bisnis.

  • Hindari bahasa lisan. Frasa yang khusus untuk bahasa Inggris lebih sulit diterjemahkan.

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

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

Pemformatan

Jenis file

Untuk keterbacaan, atur agar baris ditampilkan pada 80 karakter. Link atau cuplikan kode yang panjang dapat 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

  • Gunakan daftar berurutan untuk menjelaskan cara menyelesaikan tugas dengan langkah-langkah
  • Gunakan daftar tidak berurutan untuk mencantumkan hal-hal yang tidak berbasis tugas. (Masih harus ada semacam urutan, seperti abjad, kepentingan, dll.)
  • Menulis dengan struktur paralel. Misalnya:
    1. Buat semua item daftar menjadi kalimat.
    2. Mulailah dengan kata kerja yang memiliki tenses 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>: Bantuan dan opsi cetak 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 menambahkan daftar isi manual.

Kode

Contoh kode adalah sahabat developer. Anda mungkin sudah tahu cara menulisnya, tetapi berikut beberapa tipsnya.

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

Blok kode

  • Buat cuplikan dengan durasi singkat. Hilangkan 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 sedikit kode.
  • Gunakan gaya kode inline, bukan miring, "tanda petik", atau tebal.
    • Ya: bazel help <command>: Bantuan dan opsi cetak untuk <command>
    • Tidak: bazel help command: Mencetak bantuan dan opsi untuk "command"