Cara menggunakan antarmuka pengguna GitLab untuk pemeliharaan dokumen yang lebih mendalam
Dokumentasi memerlukan pemeliharaan seiring dengan pertumbuhan kontennya. Penulis dan peninjau dapat berkontribusi ke dokumentasi Fedora dengan mudah dan efisien melalui Antarmuka Web GitLab. Mulai dari Web IDE, pipeline CI, hingga tinjauan kolaboratif terhadap hasil rendering konten web dan persetujuan halaman, Anda dapat mengerjakan konten yang berkualitas serta menjaga dokumentasi tanpa gangguan dari proses instalasi dan konfigurasi. Artikel ini mengasumsikan bahwa Anda sudah memahami Git dan continuous integration (CI).
Pemeliharaan dokumentasi
Pemeliharaan dokumentasi dapat dilakukan dalam berbagai bentuk.
-
Ketepatan teknis
-
Keterbaruan informasi
-
Pengurutan dokumentasi secara logis
-
Konsistensi dalam penyajian
-
Penerapan template standar, atribut, dan konvensi secara menyeluruh di seluruh repositori dokumentasi
-
Penggunaan pipeline CI untuk mengotomatiskan pemeriksaan kualitas dokumentasi
Bagian-bagian berikut menjelaskan langkah demi langkah cara memelihara dan terus meningkatkan kualitas repositori Fedora Docs menggunakan alat bawaan GitLab.
GitLab Web IDE
Diluncurkan sebagai bagian dari rilis GitLab 15.7 pada Desember 2022, Web IDE baru menyediakan penjelajah berkas, editor teks, dan kontrol sumber dalam satu tempat.
Penjelajah (Explorer)
Panel penjelajah di sisi kiri membantu menemukan struktur repositori dan daftar berkas dalam Fedora Docs. Struktur repositori standar memungkinkan kontributor menavigasi berkas dan mereferensikan beberapa halaman dengan cepat.
Editor teks
Setelah melakukan perubahan, buka ikon Source Control di bilah aktivitas dan klik Changes di bawah tombol Commit & Push untuk melihat daftar berkas yang Anda ubah dalam tampilan berdampingan. Jika Anda melakukan beberapa commit, bagian Changes akan menampilkan ringkasan dari semua perubahan yang Anda lakukan.
Jika Anda mengklik Create MR, Anda akan diarahkan ke fork Anda untuk membuat merge request. Opsi Go to project cocok digunakan ketika Anda membuat beberapa commit kecil tahap demi tahap dan ingin menggabungkannya menjadi satu.
Pipeline CI
Pengujian otomatis untuk dokumentasi memicu validasi sintaks, kesalahan gaya, dan membantu memperbaikinya sebelum MR digabungkan. Tujuannya adalah menjaga konsistensi dokumentasi secara menyeluruh dan memastikan kepatuhan terhadap panduan gaya. Tim dokumentasi memperkenalkan linter dokumentasi berbasis sintaks untuk beberapa repositori, di mana Anda dapat menemukan berkas konfigurasi Vale. Beberapa kontributor menulis artikel tanpa memahami panduan gaya dan keterbacaan. Lihat konfigurasi Vale untuk CI di repositori terkait:
Linter dokumentasi menjalankan lebih dari 20 jenis pengujian:
-
Untuk memicu pipeline CI guna memindai kesalahan apa pun.
-
Untuk memeriksa kata dan struktur dokumentasi.
-
Untuk memverifikasi validitas tautan.
-
Untuk memeriksa keterbacaan serta menjalankan pengujian bahasa yang inklusif dan lainnya.
Perlu diketahui bahwa linter membantu Anda menulis dengan lebih baik, tetapi tidak secara otomatis memperbaiki kesalahan.
Tinjauan visual
Dengan aplikasi tinjauan, pratinjau langsung dari halaman yang sudah dirender akan ditampilkan ketika Anda mengklik ikon view app atau view deployment pada preview MR_number.
Anda akan diarahkan ke halaman Artifacts-build yang menampilkan nomor pekerjaan dan tautan ke halaman hasil render yang di-host di GitLab. Klik tautan tersebut untuk meninjau konten sebagaimana Anda biasanya menjalankan skrip Docsbuild di komputer lokal.
Melihat pratinjau perubahan selama tinjauan MR memfasilitasi kolaborasi yang lebih erat untuk menemukan kesalahan dan memberikan saran guna meningkatkan kualitas konten.
Tombol View app akan hilang setelah MR digabungkan.
Want to help? Learn how to contribute to Fedora Docs ›