Berkontribusi pada Quick Docs

Hanku Lee, Peter Boy, Fedora Documentation Team Last review: 2023-03-19
Quick Docs adalah kumpulan panduan singkat dan tutorial yang lebih lengkap untuk pengguna Fedora Linux. Kami menyediakan beberapa tips dan saran tentang cara berkontribusi pada Quick Docs.

Jenis-jenis konten

Fedora Quick Docs terdiri dari dua jenis artikel.

Panduan langkah demi langkah

Ciri-cirinya adalah

  • Ditujukan untuk membantu saat bekerja dengan Fedora

  • Berorientasi pada masalah dan tujuan

  • Biasanya teks ini relatif singkat, tidak lebih dari 60.000 karakter

  • Biasanya berupa petunjuk langkah demi langkah untuk menyelesaikan masalah atau tugas kecil dan spesifik, tanpa penjelasan yang mendetail

Tutorial

Ciri-cirinya adalah

  • Ditujukan untuk membantu dalam mempelajari perangkat lunak atau kumpulan perangkat lunak tertentu untuk tujuan spesifik di Fedora

  • Dikenal karena belajar keterampilan baru

  • Seringkali teks tersebut lebih panjang dari 80.000 karakter

  • Pastikan pemahaman terhadap fitur-fitur yang diikuti dengan panduan langkah demi langkah penggunaan program perangkat lunak

Jika posting Anda tidak sesuai dengan kedua kategori tersebut, pertimbangkan untuk membuat artikel di bawah kategori Administration Tools atau di halaman Beranda. Tempat terbaik untuk bertanya adalah di discussion.fedoraproject.org #docs.

Siapa yang dapat berkontribusi

Siapa pun dapat berkontribusi dan semua orang dipersilakan! Namun, ada beberapa persyaratan kecil dan mudah dipenuhi. Yang paling penting adalah memiliki akun Fedora yang telah menandatangani Perjanjian Kontributor Proyek Fedora (https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement). Hal ini sangat penting untuk melindungi Fedora dari potensi masalah lisensi. Tentu saja, pengetahuan tentang bahasa markup AsciiDOC akan sangat membantu, tetapi Anda tetap bisa berkontribusi dengan baik tanpa menguasainya. Hal ini terutama berlaku saat mengoreksi dan merevisi artikel yang sudah ada. Anda dapat dengan mudah mengikuti alur yang sudah ada.

Fakta pentingnya adalah, tidak diperlukan pengetahuan khusus! Anda tidak perlu tahu apa pun tentang desktop publishing, trik pemformatan yang rumit, atau hal-hal semacam itu.

Rentang kontribusi yang layak dan diperlukan sangat luas. Setiap orang dapat memberikan kontribusi yang penting. Peran/tugas yang umum adalah;

  • penulis

  • peninjau teknis

  • pemeriksaan ejaan

  • perbaikan redaksi

  • Organisasi QuickDoc

  • merevisi artikel

Cara menemukan tugas

Baik itu tautan yang rusak, tangkapan layar antarmuka pengguna grafis yang sudah usang, kesalahan teknis, atau kesalahan tata bahasa, setiap kontribusi sekecil apa pun membantu pengguna Fedora Linux.

Saat membaca sebuah artikel

Kesempatan terbesar untuk berkontribusi datang dari membaca artikel itu sendiri. Setiap kali Anda menemukan kesalahan, kelalaian, atau kalimat yang tidak jelas, Anda dapat memberikan saran perbaikan secara langsung. Di bagian header setiap artikel terdapat tautan ke 2 dari 3 alat untuk berkontribusi.

easy contrib
Gambar 1. Tautan ke alat-alat yang berkontribusi

Tombol paling kanan mengarah ke sistem tiket di mana Anda dapat melaporkan masalah.

report issue
Gambar 2. Tunjukkan kesalahan yang Anda temukan

Bidang subjek sudah berisi tautan ke dokumen yang terkena dampak. Jangan ubah tautan tersebut. Silakan berikan deskripsi masalah dan, jika memungkinkan, berikan saran modifikasi yang ringkas, idealnya dalam format siap salin dan tempel.

Jika Anda belum masuk ke Pagure, jendela login FAS akan terbuka terlebih dahulu.

Tautan kedua membuka editor web, yang dapat Anda gunakan untuk memasukkan perubahan yang diusulkan langsung ke dalam teks.

report issue
Gambar 3. Editor web

Langkah-langkah selanjutnya dijelaskan secara rinci dalam artikel Cara mengedit berkas di antarmuka web Pagure.

Menugaskan masalah secara mandiri

Anda dapat menemukan dan berkontribusi pada perubahan yang diperlukan dengan mengikuti papan masalah Quick Docs di https://pagure.io/fedora-docs/quick-docs/issues, di mana pengguna berbagi kesalahan dalam dokumentasi atau saran untuk memperbaikinya.

Jika Anda menemukan masalah yang sesuai dengan minat dan keahlian Anda, klik tautan “ambil” di bagian kanan atas untuk menugaskan masalah tersebut kepada diri Anda sendiri.

assign issues
Gambar 4. Tugaskan masalah

Cara berkontribusi

Quick Docs menggunakan CMS yang sama dengan semua Fedora Docs lainnya, jadi alat-alatnya juga sama. Anda dapat menemukan panduan detail di bagian Alat Kontribusi.

Permintaan Pull dan tinjauan

Dalam kedua kasus tersebut, alur kerja mengikuti model “pull request” atau “merge request”. Perubahan tidak dilakukan pada teks yang sudah ada dan diterbitkan, melainkan pada versi sampingan. Ketika pekerjaan selesai, permintaan penggabungan (“merge request”) akan diajukan. Anggota komunitas akan meninjau perubahan tersebut dan dapat memulai diskusi atau menerima perubahan tersebut. Perubahan tersebut kemudian akan digabungkan ke dalam versi yang diterbitkan. Dengan demikian, kami mengikuti prinsip 4-mata.

Pull Requests memfasilitasi alur kerja kolaboratif antara penulis dan peninjau, di mana komentar, suntingan, dan commit pada Pull Request berfungsi sebagai proses peninjauan.

Langkah-langkah individu sebagian besar bersifat otomatis. Rincian dijelaskan dalam alat-alat yang bersangkutan.

Pemberitahuan setelah PR

Anda mungkin ingin memantau perkembangan selanjutnya setelah PR. Itulah fungsi dari fitur Watch.

Status tampilan di tengah laporan Quick Doc memiliki empat opsi. Pilih salah satu opsi di bawah ini.

  • Masalah dan Permintaan Pull

  • Pantau Komitmen

  • Pantau Masalah, Permintaan Pull, dan Komitmen

  • Tidak ditonton

Pemberitahuan akan dikirim ke email Anda sesuai dengan pengaturan pengguna di Pagure.

watch notification
Gambar 5. Opsi pemberitahuan

Jika Anda tidak menerima tanggapan dari para peninjau setelah mengirimkan PR Anda lebih dari seminggu, tinggalkan komentar di PR untuk mengikuti perkembangan.

Hal-hal yang perlu diperhatikan

Kemudahan membaca

  • Tulis kalimat-kalimat pendek yang disusun dalam paragraf-paragraf pendek. Hindari teks yang terlalu panjang saat membuat konten.

  • Gunakan struktur yang jelas dan format minimal untuk alur bacaan yang lebih baik

Ketaatan terhadap panduan gaya

Alih-alih mengkritik konsistensi gaya penulisan dan kesalahan tata bahasa, para peninjau mendorong penulis untuk membaca Panduan Gaya Dokumen. Jika Anda ingin melakukan pengujian otomatis, jalankan vale linter secara lokal Periksa Dokumen Anda Menggunakan Vale.

Kumpulan aturan

Selain panduan gaya, berikut adalah beberapa aturan yang harus diikuti oleh kontributor.

  • Tim Dokumen menangani bug dalam dokumentasi dengan prinsip yang sama seperti bug dalam kode, di mana integrasi berkelanjutan, pengujian otomatis, dan perbaikan bertahap untuk kualitas dokumentasi diterapkan.

  • Semua perubahan pada Quick Docs harus dilakukan melalui Pull Requests dari proyek yang telah difork. Proyek Quick Docs tidak mendukung pengiriman langsung ke repositori hulu.

  • Jika Anda memperbarui konten tentang fitur baru, rilis, atau konten baru, uji aplikasi dan prosesnya di sistem baru atau Virtual Machine yang baru diinstal dengan semua pembaruan yang telah diterapkan.

  • Jangan gunakan tangkapan layar terminal. Sediakan blok kode sumber dalam bahasa pemrograman tertentu atau perintah shell.

  • Jalankan linter prosa seperti Vale secara lokal sebelum mengirimkan pull request (PR). Periksa tautan ini: Cara memeriksa gaya dokumentasi dengan Vale

Template artikel

= JUDUL_ARTIKEL
PENULIS_1; PENULIS_2; PENULIS_3 :nomor_revisi: Fxy :tanggal_revisi: yyyy-mm-dd :kategori: KATEGORI :tag: TAG_01 TAG_02 TAG_03 ... TAG_n //:alias_halaman: OPSIONAL

// Informasi tambahan yang berguna dalam bentuk bebas (opsional) sebagai komentar


[abstrak] Pernyataan misi dalam 2-3 kalimat

Catatan:

Baris penulis

Kami ingin mencantumkan 3 penulis terakhir yang berkontribusi pada artikel ini dalam hal substansi dan konten. Tentu saja, setiap kontribusi sangat dihargai! Namun, pada posisi yang menonjol ini, kami tidak ingin menyertakan perubahan minor, seperti kesalahan ejaan atau koreksi kata-kata individu.

Sebagai alternatif, gunakan Tim Dokumentasi Fedora

nomor revisi

Gunakan nomor rilis yang diawali dengan 'F', misalnya F37, atau rentang rilis, misalnya F36,F37,F38 atau F33-F37. Sebisa mungkin gunakan spesifikasi yang tepat dan gunakan 'semua' hanya dalam kasus-kasus khusus

revdate

Tanggal terakhir seseorang memeriksa konten untuk kategori:: Pilih hanya satu kategori dari daftar di bawah ini. Kategori adalah wajib! Kategori (dan tag) adalah satu-satunya cara untuk menemukan artikel.

tag

satu atau lebih tag dari daftar di bawah ini

abstrak

1-3 kalimat yang menggambarkan isi dan tujuan. Hindari pengulangan, misalnya mengulang judul

Anda juga dapat mengunduh templat dengan mengklik tautan unduh templat untuk memudahkan prosesnya.

Daftar kategori yang dapat dipilih

Anda hanya dapat memilih satu kategori!

  • Administrasi

  • Instalasi

  • Pengelolaan perangkat lunak

  • Peningkatan

Daftar ini jauh dari lengkap! TBD: Perluasan daftar kategori

Daftar tag yang dapat dipilih

Anda dapat memilih beberapa tag!

  • Tag tingkat 1, pilih setidaknya satu:

    • Cara

    • Panduan

  • Tag tingkat 2, pilih beberapa, tidak ada jika berlaku secara sistem

    • Workstation

      • Gnome

      • KDE

      • XFCE

    • Silverblue

    • Kinoite

    • Server

    • CoreOS

    • IoT

  • Tag tingkat 3, opsional, pilih beberapa

    • Pemecahan Masalah / Pemecahan Masalah Teknis

    • Cetak / Pindai

    • SELinux

Anda bebas memilih tag tingkat 3 tambahan jika tidak ada yang sesuai dengan kontribusi Anda.

Tim Dokumen membutuhkan bantuan Anda

Bantu kami dalam menangani masalah, permintaan pull (PR), proses onboarding kontributor baru, atau menjaga agar kumpulan artikel kami tetap up-to-date. Terima kasih!

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