Panduan gaya dokumen Bazel

Laporkan masalah Lihat sumber

Terima kasih telah berkontribusi pada dokumentasi Bazel. Hal ini berfungsi sebagai panduan gaya dokumentasi singkat untuk membantu Anda memulai. Untuk pertanyaan gaya yang tidak terjawab dalam 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 tingkat membaca kelas lima.
  • Konsisten. Gunakan kata atau frasa yang sama untuk konsep 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.

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, mereka sesuai dengan TOC tanpa pembungkus (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 judul bersifat konseptual, mungkin didasarkan pada pemahaman, tetapi tulis 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. 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 didefinisikan 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 serupa, contoh, atau cara lain untuk melakukan eksplorasi.

Subject

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

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

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

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

  • Hindari kata "we". Dalam dokumen pengguna, tidak ada penulis; cukup beri tahu pengguna apa yang mungkin dilakukan.

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

Sementara

Jika memungkinkan, hindari istilah yang mengarahkan hal pada waktu tertentu, seperti mereferensikan tanggal tertentu (K2 2022) atau mengatakan "sekarang", "saat ini", atau "segera". Ini akan cepat habis dan bisa salah jika proyeksi di masa mendatang. Sebagai gantinya, tentukan level versi, misalnya "Bazel X.x dan yang lebih baru mendukung <feature> atau link masalah GitHub.

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

Tense

  • Menggunakan present tense. Hindari ketegangan masa lalu atau masa depan kecuali jika benar-benar diperlukan untuk kejelasan.

    • 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 error.

  • Jika memungkinkan, gunakan kalimat aktif (saat subjek bertindak atas suatu objek) bukan suara pasif (saat objek ditindaklanjuti oleh subjek). Umumnya, suara 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.
    • No: X dimulai oleh Bazel, dan setelah itu Y akan dibangun dengan output.

Nuansa

Tulis dengan nada bisnis yang ramah.

  • Hindari bahasa sehari-hari. Akan lebih sulit untuk menerjemahkan frasa 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 tersebut kepada seseorang yang ingin tahu tentang teknologi, tetapi tidak tahu detailnya.

Pemformatan

Jenis file

Agar mudah dibaca, kemas baris pada 80 karakter. Tautan panjang atau cuplikan kode mungkin lebih panjang, namun harus dimulai pada 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 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. (Harus tetap ada urutan, seperti abjad, tingkat kepentingan, dll.)
  • Menulis dengan struktur paralel. Misalnya:
    1. Membuat semua kalimat item daftar.
    2. Mulailah dengan kata kerja yang memiliki bentuk waktu yang sama.
    3. 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>: Mencetak bantuan dan opsi untuk <command>
    • No: command bantuan bazel: Mencetak bantuan dan opsi untuk "command"

  • Khusus untuk contoh kode yang rumit, gunakan placeholder yang sesuai dengan konteks.

Daftar isi

Gunakan TOC yang dibuat otomatis yang didukung oleh situs. Jangan tambahkan TOC manual.

Kode

Contoh kode adalah teman terbaik para developer. Anda mungkin sudah tahu cara menulisnya, tapi berikut ini beberapa tips untuk Anda.

Jika merujuk pada cuplikan kode berukuran kecil, Anda dapat menyematkannya dalam sebuah 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.
  • 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>: Mencetak bantuan dan opsi untuk <command>
    • No: command bantuan bazel: Mencetak bantuan dan opsi untuk "command"