Panduan gaya dokumen Bazel

Terima kasih telah berkontribusi untuk dokumentasi Bazel. 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

Dokumen Bazel harus menjunjung prinsip-prinsip berikut:

  • Ringkas. Gunakan kata sesedikit mungkin.
  • Hapus. Gunakan bahasa sederhana. Menulis 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 header sesingkat mungkin. Dengan cara ini, mereka sesuai dengan TOC tanpa pembungkus.

    • Ya: Izin
    • Tidak: Catatan singkat tentang izin

  • Gunakan kapitalisasi kalimat untuk {i>heading<i}

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

  • Cobalah untuk membuat {i>heading<i} berbasis tugas atau dapat ditindaklanjuti. Jika {i>heading<i} bersifat konseptual, {i>heading<i} mungkin didasarkan pada pemahaman, tetapi menulis apa yang dilakukan pengguna.

    • Ya: Mempertahankan urutan grafik
    • Tidak: Terkait dengan mempertahankan urutan grafik

Nama

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

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

  • Jaga agar tetap konsisten. Jangan perkenalkan nama baru untuk konsep yang ada. Jika ada, gunakan istilah yang didefinisikan dalam Glosarium.

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

Cakupan halaman

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

Subject

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

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

    • Ya: Untuk membuat kode Java menggunakan Bazel, Anda harus menginstal JDK.
    • MAYBE: 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 pengelola, kontributor, migrasi, atau peran lainnya.

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

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

Temporal

Jika memungkinkan, hindari istilah yang mengarahkan sesuatu tepat waktu, seperti merujuk tanggal tertentu (Kuartal 2 2022) atau menyebutkan "sekarang", "saat ini", atau "segera". Semua ini akan hilang dengan cepat dan bisa salah jika menjadi proyeksi di masa mendatang. Sebagai gantinya, tentukan level versi, seperti "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 akan dilakukan pada Oktober 2017.

Tense

  • Gunakan present tense. Hindari ketegangan masa lalu atau masa mendatang kecuali benar-benar diperlukan untuk kejelasan.

    • Ya: Bazel akan mengalami 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 (jika subjek bertindak atas suatu objek), bukan kalimat pasif (saat objek ditindaklanjuti oleh subjek). Umumnya, kalimat aktif memperjelas kalimat 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.
    • Tidak: X dimulai oleh Bazel, lalu Y akan dibuat dengan output.

Nuansa

Tulis dengan nada yang ramah bisnis.

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

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

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

Pemformatan

Jenis file

Agar mudah dibaca, gabungkan baris pada 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 detail selengkapnya, lihat [Menginstal Bazel].
    • Tidak: Untuk detail selengkapnya, lihat [di sini].

  • Akhiri kalimat dengan link, jika memungkinkan.

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

Daftar

  • Menggunakan daftar yang diurutkan untuk menjelaskan cara menyelesaikan tugas dengan langkah-langkahnya
  • Gunakan daftar yang tidak diurutkan untuk membuat daftar hal-hal yang tidak berbasis tugas. (Harus ada urutannya, seperti alfabet, tingkat kepentingan, dll.)
  • Menulis dengan struktur paralel. Misalnya:
    1. Buat semua item daftar menjadi kalimat.
    2. Mulailah dengan kata kerja yang memiliki masa 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. Dalam Markdown, ganti tanda kurung sudut dengan garis miring terbalik: \<example\>.

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

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

Code

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

Jika mereferensikan cuplikan kode berukuran 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. Hilangkan semua teks yang berlebihan atau tidak perlu dari contoh kode.
  • Dalam Markdown, tentukan jenis blok kode dengan menambahkan bahasa sampel.
```shell
...
  • Memisahkan perintah dan output ke dalam blok kode yang berbeda.

Pemformatan kode sebaris

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