Panduan gaya dokumen Bazel

Laporkan masalah Lihat sumber

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

Prinsip penetapan

Dokumen Bazel harus menerapkan prinsip-prinsip berikut:

  • Ringkas. Gunakan sesedikit mungkin kata.
  • Hapus. Gunakan bahasa yang sederhana. Menulis tanpa jargon untuk level 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 promise untuk masa depan.

Penulisan

Bagian ini berisi tips menulis dasar.

Judul

  • Judul tingkat halaman dimulai pada H2. (Judul H1 digunakan sebagai judul halaman.)
  • Buat header sesingkat mungkin. Dengan cara ini, keduanya akan masuk ke dalam ToC tanpa digabungkan.

    • Ya: Izin
    • Tidak: Catatan singkat tentang izin
  • Gunakan kapitalisasi kalimat untuk judul

    • Ya: Siapkan ruang kerja Anda
    • Tidak: Siapkan Ruang Kerja Anda
  • Coba buat judul menjadi tugas atau dapat ditindaklanjuti. Jika judul bersifat konseptual, judul mungkin didasarkan pada pemahaman, tetapi menulis sesuai tindakan pengguna.

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

Nama

  • Gunakan 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.
  • Pertahankan konsistensinya. Jangan perkenalkan nama baru untuk konsep yang sudah 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 harus ditentukan di awal. Dengan begitu, pembaca dapat menemukan apa yang mereka butuhkan dengan lebih cepat.

    • Ya: Halaman ini mencakup 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 eksplorasi lain yang serupa.

Subject

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

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

    • Ya: Untuk mem-build 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. Audiens lainnya dapat mencakup pemelihara, kontributor, migran, atau peran lainnya.

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

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

Temporer

Jika memungkinkan, hindari istilah yang berorientasi pada waktu, seperti mereferensikan tanggal tertentu (Kuartal 2 2022) atau mengucapkan "now", "saat ini", atau "segera". Tidak optimal dan bisa salah jika merupakan proyeksi di masa mendatang. Sebagai gantinya, tentukan level versi, seperti "Bazel X.x dan versi yang lebih baru yang mendukung <feature> atau link masalah GitHub.

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

Tense

  • Menggunakan present tense. Hindari tegangan 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: Bazel akan menemukan dependensi yang tidak sesuai dengan aturan ini, Bazel akan mengeluarkan error.
  • Jika memungkinkan, gunakan kalimat aktif (jika subjek bertindak pada objek) bukan objek pasif (tempat objek 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 mem-build Y.
    • No: X dimulai oleh Bazel, lalu setelah itu Y akan di-build dengan output.

Nuansa

Tulis dengan gaya yang ramah bisnis.

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

    • Ya: Kumpulan aturan yang baik
    • Tidak: Jadi, apa yang dimaksud dengan aturan yang baik?
  • Hindari bahasa yang terlalu formal. Tulis seolah-olah Anda menjelaskan konsep tersebut kepada seseorang yang ingin tahu tentang teknologi, tetapi tidak tahu detailnya.

Pemformatan

Jenis file

Agar mudah dibaca, gabungkan baris dengan panjang 80 karakter. Link panjang atau cuplikan kode mungkin lebih panjang, tetapi harus dimulai pada baris baru. Contoh:

  • Gunakan teks link deskriptif, bukan "di sini" atau "di bawah". Praktik ini mempermudah 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 informasi selengkapnya.

Daftar

  • Gunakan daftar yang diurutkan untuk menjelaskan cara menyelesaikan tugas dengan langkah-langkah
  • Gunakan daftar yang tidak diurutkan untuk mencantumkan hal-hal yang bukan berbasis tugas. (Harus tetap ada urutannya, seperti alfabet, nilai penting, dll.)
  • Menulis dengan struktur paralel. Misalnya:
    1. Buat semua kalimat item daftar.
    2. Mulai dengan kata kerja yang sama bentuknya.
    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, konversi tanda kurung sudut dengan garis miring terbalik: \<example\>.

    • Ya: bazel help <command>: Mencetak bantuan dan opsi untuk <command>
    • Tidak: bazel membantu perintah: Mencetak bantuan dan opsi untuk "perintah"
  • Khusus untuk contoh kode yang rumit, gunakan placeholder yang relevan dalam konteks.

Daftar isi

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

Kode

Contoh kode adalah sahabat developer. Anda mungkin sudah mengetahui cara menulis ini, tetapi ada beberapa tips.

Jika merujuk sedikit cuplikan 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 tidak perlu atau tidak perlu dari contoh kode.
  • Di Markdown, tentukan jenis blok kode dengan menambahkan bahasa sampel.
```shell
...
  • Pisahkan perintah dan output ke dalam blok kode yang berbeda.

Pemformatan kode inline

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