Berpartisipasi dalam meningkatkan dan memperluas artikel-artikel di Docs

Tim Dokumentasi Fedora Versi F36 and newer Last review: 2023-05-01

Dokumen ini menjelaskan cara bekerja dengan sistem penerbitan yang digunakan untuk membangun situs web Dokumentasi Fedora. Dokumen ini akan memandu Anda dalam berkontribusi pada dokumentasi yang sudah ada serta membuat kumpulan konten baru sepenuhnya dan menerbitkannya dalam versi asli bahasa Inggris serta terjemahan apa pun yang mungkin ada.

Ada banyak cara berbeda untuk berkontribusi pada dokumentasi Fedora. Beberapa di antaranya dirancang untuk memudahkan kontribusi tanpa memerlukan pengetahuan teknis tentang Sistem Manajemen Konten Web (Web Content Management Systems) dan cara menyimpan serta mengelola kontribusi Anda. Alat ini menangani semua masalah tersebut untuk Anda. Hal ini memungkinkan penulis untuk fokus pada topik yang sedang dibahas.

Silakan kunjungi halaman kami. Jika Anda menemukan halaman dokumentasi yang mengandung kesalahan atau ketidakakuratan, gunakan salah satu alat kontribusi yang dijelaskan di bawah ini untuk memperbaiki halaman tersebut. Jika Anda memiliki pertanyaan, jangan ragu untuk menghubungi tim Dokumentasi.

Alat penulisan lokal dirancang untuk menyediakan lingkungan kerja yang kuat bagi penulis berpengalaman. Alat-alat ini memungkinkan kerja yang efisien bahkan pada koleksi teks besar dan kompleks yang saling terkait. Alat-alat ini ditujukan untuk penulis yang berpengalaman.

Bagaimana cara kerjanya

Dokumentasi Fedora menggunakan Antora untuk membangun dan mengelola situs web. Dokumentasi ini merupakan konten statis yang relatif tetap, dengan pembaruan sesekali dari waktu ke waktu. Inilah tepatnya yang menjadi spesialisasi Antora. Antora mengumpulkan dokumen teks statis dan mengubahnya menjadi situs web lengkap, termasuk navigasi, tautan, format, penempatan, penyesuaian untuk perangkat output yang berbeda, dan sebagainya. Untuk informasi umum lebih lanjut tentang sistem penerbitan Antora, lihat Situs Web Antora dan Dokumentasi Antora.

Sebagai seorang penulis, Anda fokus pada konten dan menulis dengan bebas.

Prosedur umum

Prinsip 4-mata berlaku untuk dokumentasi Fedora. Setiap kontribusi ditinjau oleh penulis yang berbeda. Setelah Anda menyelesaikan teks atau modifikasi teks, sistem akan membuat “Pull Request” atau “Merge Request” untuk mengintegrasikan teks Anda ke dalam tubuh dokumentasi. Hal ini memicu penulis lain, anggota dewan, atau anggota yang terlibat dalam bagian tubuh dokumentasi yang bersangkutan, untuk memulai tinjauan dan baik memulai proses inklusi atau memulai diskusi. Berikan waktu 2 hingga 3 hari untuk mendapatkan tanggapan atas permintaan.

Beberapa latar belakang teknis

Fedora menggunakan AsciiDoc untuk memformat teks dengan cara yang sederhana dan efisien. Format ini mengikuti gaya penulisan alami dalam catatan sehari-hari untuk struktur dan penekanan. Dengan cara ini, Anda dapat menggunakan editor apa pun, termasuk hampir semua pengolah kata yang dapat mengedit dan menyimpan teks AsciiDoc. Lebih lanjut tentang hal ini di bawah ini.

Dokumen teks AsciiDoc disimpan dalam serangkaian repositori Git. Sistem ini sangat populer di kalangan pengembang perangkat lunak, tetapi juga sangat mampu untuk mengelola dokumen teks. Git mendorong dan memfasilitasi penerapan prinsip 4-mata melalui alur kerja “Pull (atau Merge) Request”. Anda hanya perlu memperhatikan detail alur kerja ini jika ingin menyiapkan lingkungan kerja lokal yang ditujukan untuk kontribusi profesional dan rutin. Semua alat lain akan menangani langkah-langkah yang diperlukan di latar belakang.

Persyaratan

Persyaratan untuk berkontribusi pada dokumentasi Fedora Docs adalah:

Alat-alat

Cara cepat: Tombol ‘Edit’

  • Lakukan perubahan pada satu berkas untuk perbaikan kecil langsung dari antarmuka web Git Forge.

  • Akses tulis ke repositori hulu diperlukan.

  • Gunakan sebagai pengecualian (tanpa proses peninjauan), bukan sebagai opsi yang direkomendasikan.

Cara mudah: Web IDE Git Forge

  • Lakukan perubahan pada beberapa berkas secara langsung melalui antarmuka web Git Forge.

  • Tidak perlu menginstal apa pun di komputer lokal atau menjalankan perintah Git di terminal.

  • Permintaan Pull untuk proses peninjauan (Permintaan Merge di GitLab)

  • Anda tidak memerlukan izin khusus atau akses tulis ke proyek asli.

Cara fleksibel dan canggih: Buat lingkungan penulisan lokal

  • Bekerja dengan beberapa berkas dan repositori secara offline sesuai kecepatan Anda menggunakan editor teks dan terminal pilihan Anda.

  • Anda dapat membangun dan merender halaman secara lokal untuk menguji perubahan Anda menggunakan kontainer Podman.

Cara-cara umum untuk berkontribusi

Dapat dibedakan beberapa jenis kontribusi yang khas untuk dokumentasi Fedora, di mana alat-alat yang tersedia cocok untuk tujuan yang berbeda-beda.

Ada banyak cara untuk berbagai jenis kontribusi. Misalnya, memperbaiki kesalahan ketik, menambahkan informasi singkat atau tautan, memperbarui artikel, atau menulis artikel baru.

Perbarui halaman dokumentasi yang sudah ada

Tugas ini melibatkan perubahan kecil. Misalnya, perbaikan kesalahan ketik, penambahan informasi singkat atau tautan, atau koreksi pada teks. Jenis perubahan ini sangat diperlukan setiap kali dokumentasi perlu diperbarui untuk versi perangkat lunak baru.

Tombol Edit Berkas sangat berguna untuk tujuan ini.

Perluas lingkup dokumentasi yang sudah ada

Tugas ini melibatkan penambahan satu atau lebih bab baru atau bagian dengan beberapa bab. Misalnya, menambahkan teknik kontainer lain ke dalam dokumentasi kontainerisasi.

Web IDE adalah alat yang praktis untuk tujuan ini. Lingkungan penulisan lokal juga dapat digunakan, tetapi mungkin memerlukan terlalu banyak beban jika Anda ingin berkontribusi pada satu dokumen saja.

Sangat disarankan untuk mempresentasikan rencana tersebut di salah satu saluran komunikasi Docs sebelum memulai. Anda mungkin mendapatkan saran dan tips mengenai konten, tetapi juga mengenai pengeditan. Misalnya, struktur berkas dan konvensi penamaan.

Perkenalkan area dokumentasi baru

Tugas ini melibatkan bidang subjek yang baru dan luas, seperti perangkat lunak baru atau alat administrasi baru. Misalnya, penambahan beberapa bagian dan bab, serta pembuatan repositori baru yang terpisah.

Untuk jenis ini, menyiapkan lingkungan penulisan lokal sangat berguna dan layak dilakukan.

Dalam hal ini, diskusi terlebih dahulu dengan tim Docs diperlukan, setidaknya untuk menyiapkan prasyarat teknis.

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