Panduan Gaya Penulisan Dokumen Fedora

Tim Dokumentasi Fedora <https://discussion.fedoraproject.org/tag/docs-team> 2023-04-21
Panduan ini menyediakan pedoman gaya dan penggunaan istilah yang disarankan untuk Dokumentasi Fedora Linux. Tim dokumentasi membuat panduan ini untuk menjaga ketepatan dan konsistensi dalam dokumentasi.

Panduan gaya penulisan

Tulislah dengan jelas dan gunakan kalimat yang lebih pendek

Semakin panjang dokumentasi pengguna, semakin sulit untuk dipahami. Menulis secara ringkas (langsung pada intinya) itu baik. Kejelasan lebih penting.

Hindari penggunaan kalimat pasif

Kalimat pasif menggunakan objek dari sebuah kalimat sebagai subjeknya. Sebagai contoh

  • Kalimat aktif: Pasukan mengalahkan musuh.

  • Kalimat pasif: Musuh dikalahkan oleh pasukan.

Berhati-hatilah terhadap penggunaan gerund (-ing)

Bentuk ini menunjukkan kalimat pasif. Ubah kalimat Anda agar terdengar lebih kuat. Sebagai contoh:

  • Lemah, kalimat pasif: Mengatur opsi konfigurasi foobar akan membuat aplikasi mendengarkan pada semua antarmuka.

  • Kuat, kalimat aktif: Atur opsi konfigurasi foobar agar aplikasi mendengarkan pada semua antarmuka.

Hindari penggunaan bentuk masa depan yang tidak perlu

Kecuali Anda benar-benar membahas rencana atau publikasi di masa depan, gunakan bentuk waktu sekarang.

  • Tidak perlu: Saat Anda memilih Jalankan, program Anda akan dimulai.

  • Tepat: Saat Anda memilih Jalankan, program Anda dimulai.

Hindari terlalu sering menggunakan kata kerja to be dalam kalimat

Terlalu banyak menggunakan adalah membuat kalimat menjadi lemah. Cobalah gunakan bentuk kata kerja dari kata yang Anda tempatkan di bagian lain kalimat. Sering kali Anda cukup menghapus kata tertentu, atau gunakan bentuk imperatif (berbentuk perintah atau saran).

  • Lemah: Zambone adalah aplikasi yang digunakan untuk mengelola dokumen pribadi Anda di server.

  • Kuat: Zambone mengelola dokumen pribadi Anda di server. Atau: Gunakan Zambone untuk mengelola dokumen pribadi Anda di server.

  • Lemah: Saat menyiapkan server file, penting untuk merencanakan struktur direktori dengan hati-hati.

  • Kuat: Rencanakan struktur direktori server file dengan hati-hati sebelum Anda menyiapkannya.

Gunakan bahasa Inggris Amerika standar untuk ejaan dan perbedaan internasional lainnya

Bahasa Inggris Amerika adalah lingua franca untuk keseluruhan Proyek Fedora.

Buat alur yang mulus dari informasi umum menuju instruksi khusus

Susun artikel Anda dengan abstrak, poin-poin penting, dan markup AsciiDoc yang esensial.

Hindari teks yang terlalu panjang

Tulisan yang bertele-tele sulit dibaca. Sebagai gantinya, atur teks menggunakan paragraf, poin, dan langkah bernomor. Ini membantu pengguna memahami teks dengan cepat dan, yang terpenting, tidak membuatnya tampak menakutkan. Sediakan abstrak singkat di awal kumpulan paragraf yang panjang: Terutama setelah judul tingkat kedua dan ketiga ("h2" dan "h3", "==" dan "===" dalam AsciiDoc), sertakan satu kalimat atau paragraf pendek yang menjelaskan tujuan dan/atau topik dari paragraf berikutnya, sehingga pesan tersampaikan kepada pembaca dan membantu menyamakan harapan pembaca.

Panduan gaya tipografi

Gunakan huruf kapital untuk judul utama (h1) dan hanya untuk judul tersebut

Hanya kapitalisasi pada judul artikel.

  • Salah: Fedora documentation style guide

  • Benar: Fedora Documentation Style Guide

Gunakan huruf kecil pada judul posting dan judul bagian

Jangan kapitalisasi kata dalam judul artikel atau judul bagian, kecuali untuk nama diri.

  • Salah: Technical Notes and Processes

  • Benar: Technical notes and processes

Lebih sedikit lebih baik

Gunakan huruf tebal hanya untuk frasa atau pernyataan yang sangat penting.

Gunakan huruf miring untuk objek sistem yang disebutkan dalam kalimat

Elemen GUI atau CLI seperti teks tombol, entri menu, atau prompt yang ditemukan pembaca di layar, perintah, atau nama paket.

Gunakan teks sumber berformat tetap untuk input atau output baris perintah

Gunakan tanda prompt shell ($ atau #) untuk menunjukkan tingkat hak akses dan membedakan input dari output.

[source,console] ---- $ command arg1 arg2 output line1 output line2 ----
Penggunaan peringatan (admonitions)

Tips, petunjuk, dan peringatan, jika digunakan berlebihan, dapat mengganggu alur penulisan dan pembacaan. Gunakan peringatan hanya ketika benar-benar diperlukan.

Tips konten

Tips ini berkaitan dengan hal-hal yang sebaiknya dilakukan — dan dihindari — dalam instruksi untuk pengguna. Ingat bahwa ribuan pembaca mempercayai Dokumentasi Fedora untuk memberi panduan dalam menjalankan tugas. Bersikaplah bertanggung jawab dan membantu, uji contoh Anda dengan cermat, dukung praktik terbaik, dan hormati keamanan serta pilihan pengguna.

Uji proses Anda

Jika memungkinkan, gunakan mesin virtual tamu baru — atau setidaknya akun pengguna yang benar-benar baru. Jalankan proses dari awal hingga akhir untuk memastikan semuanya berfungsi. Perbaiki, ulangi, dan uji kembali!

Gunakan perangkat lunak bebas dan sumber terbuka serta perangkat lunak resmi yang dikemas

Artikel dapat membahas perangkat lunak non-FOSS yang digunakan di Fedora, jika tidak tersedia alternatif perangkat lunak FOSS untuk pengguna Fedora.

Gunakan distribusi keluarga Fedora

Kecuali artikel dokumentasi Anda secara khusus menargetkan mekanisme lintas distribusi, gunakan instalasi, kontainer, atau distribusi dalam keluarga Fedora (Fedora, CentOS, RHEL).

Perangkat lunak Copr harus disertai dengan peringatan

Sistem build Copr tidak dikelola oleh tim rilis Fedora dan tidak menyediakan build perangkat lunak resmi. Jika Anda membahas perangkat lunak dari Copr, pastikan tidak ada build resmi. Jika tidak, sertakan pernyataan seperti berikut: Copr tidak didukung secara resmi oleh infrastruktur Fedora. Gunakan paket dengan risiko Anda sendiri.

Hindari bahasa yang bersifat eksklusif

Berikut adalah contoh istilah yang harus dihindari dalam artikel:

  • blacklist/whitelist — Gunakan allowlist/denylist sebagai gantinya, yang lebih langsung menggambarkan tujuannya.

  • master/slave — Gunakan primary/secondary, primary/replica, active/passive, active/standby, atau istilah sejenis lainnya.

Gunakan gaya penulisan yang benar untuk pihak ketiga

Nama perusahaan, proyek, dan teknologi tidak selalu mengikuti aturan gaya kata dalam bahasa Inggris. Pilih gaya yang digunakan oleh situs web resmi ketika ragu. Jika sumber resmi menggunakan gaya yang tidak konsisten, gunakan pertimbangan terbaik Anda. Berikut adalah daftar yang tidak lengkap:

  • Copr, bukan COPR

  • NVIDIA, bukan Nvidia atau nVidia

  • Perl, bukan PERL

  • Red Hat, bukan Redhat atau RedHat

  • ThinkPad, bukan Thinkpad

Gambar dan tangkapan layar

Gunakan sistem Fedora standar yang baru

Jangan gunakan sistem atau pengaturan pribadi Anda. Sebaiknya buat mesin virtual dengan instalasi Fedora baru, dan lakukan langkah-langkah di sana.

Atur resolusi layar pada tingkat yang wajar, tidak terlalu tinggi

Perangkat lunak tangkapan layar khusus lingkungan desktop menghasilkan gambar dengan ukuran yang sesuai untuk artikel. Jika Anda menampilkan jendela peramban, gunakan opsi jendela aktif di perangkat lunak tangkapan layar. Gunakan opsi untuk tidak menyertakan bilah judul jendela.

Jika Anda hanya menampilkan aplikasi, jendela pop-up, atau area tertentu, gunakan opsi pemotongan otomatis yang tersedia di perangkat lunak tersebut

Jika tangkapan layar menampilkan seluruh jendela peramban, aplikasi berukuran penuh, atau layar penuh, pilih thumbnail berukuran sedang. Sertakan deskripsi gambar sebelum makro blok gambar untuk menjelaskan tindakan yang ditampilkan. Periksa halaman berikutnya untuk markup AsciiDoc.

Penggunaan konvensi penamaan direktori dan berkas

Untuk menjaga konsistensi konvensi penamaan, pertahankan judul asli artikel, gunakan nama tersebut pada subdirektori dan judul gambar.

Jalur direktori untuk gambar dalam repositori Fedora mengikuti ~/modules/ROOT/assets/images/<ARTICLENAME_SHORTEND>/.png

Contoh 1. Menamai subdirektori dan berkas
Jika judul pada tajuk H1 adalah Finding and installing Linux applications, maka nama berkasnya adalah finding-installing-linux-apps.adoc. Buat subdirektori dan tempatkan gambar di jalur berikut pada repositori lokal yang telah diklon: ~/modules/ROOT/assets/images/finding-installing-linux-apps/.png

Tips pemrosesan

Periksa ejaan dan tata bahasa

Periksa kembali hasil pekerjaan Anda sebelum membuat Pull Request.

Periksa panduan gaya Red Hat

Gunakan Vale untuk memeriksa hasil pekerjaan Anda dan memastikan kesesuaiannya dengan Panduan Gaya Red Hat.

Want to help? Learn how to contribute to Fedora Docs ›