Berkontribusi ke Dokumentasi Kubernetes

• 1: Menyarankan peningkatan kualitas konten
• 2: Berpartisipasi dalam SIG Docs
• 3: Dokumentasi Khusus Untuk Translasi Bahasa Indonesia

1 - Menyarankan peningkatan kualitas konten

Jika kamu menemukan masalah pada dokumentasi Kubernetes, atau mempunyai ide untuk konten baru, maka silakan untuk membuat isu pada Github. Kamu hanya membutuhkan sebuah akun Github dan sebuah web browser.

Pada kebanyakan kasus, pekerjaan dalam dokumentasi Kubernetes diawali dengan sebuah isu pada Github. Kontributor Kubernetes akan mengkaji, mengkategorisasi dan menandai isu sesuai kebutuhan. Selanjutnya, kamu atau anggota lain dari komunitas Kubernetes dapat membuat pull request dengan perubahan yang akan menyelesaikan masalahnya.

Membuka sebuah issue

Jika kamu mau menyarankan peningkatan kualitas pada konten yang sudah ada, atau menemukan kesalahan, maka silakan membuka sebuah isu.

1. Turun ke bagian bawah dari suatu halaman dan klik pada tombol Buat Isu. Ini akan mengantarmu pada halaman Github isu dengan beberapa tajuk yang telah diisi.
2. Deskripsikan isu atau saran untuk peningkatan kualitas. Sediakan detail sebanyak mungkin yang kamu bisa.
3. Klik Submit new issue

Setelah dikirim, cek isu yang kamu buat secara berkala atau hidupkan notifikasi Github. Pengulas (reviewer) atau anggota komunitas lainnya mungkin akan menanyakan pertanyaan sebelum mereka mengambil suatu tindakan terhadap isumu.

Menyarankan konten baru

Jika kamu memiliki ide untuk konten baru, tapi kamu tidak yakin dimana mengutarakannya, kamu tetap dapat membuat sebuah isu. Antara lain:

• Pilih halaman pada bagian yang menurutmu konten tersebut berhubungan dan klik Buat Isu.
• Pergi ke Github dan langsung membuat isu.

Bagaimana cara membuat isu yang bagus

Perhatikan hal berikut ketika membuat sebuah isu:

• Memberikan deskripsi isu yang jelas. Deskripsikan apa yang memang kurang, tertinggal, salah atau konten mana yang memerlukan peningkatan kualitas.
• Jelaskan dampak spesifik dari isu terhadap pengguna.
• Batasi cakupan dari sebuah isu menjadi ukuran pekerjaan yang masuk akal. Untuk masalah dengan cakupan yang besar, pecah isu itu menjadi beberapa isu lebih kecil. Misal, "Membenahi dokumentasi keamanan" masih sangat luas cakupannya, tapi "Penambahan detail pada topik 'Pembatasan akses jaringan'" adalah lebih spesifik untuk dikerjakan.
• Mencari isu yang sudah ada untuk melihat apakah ada sesuatu yang berhubungan atau mirip dengan isu yang baru.
• Jika isu yang baru berhubungan dengan isu lain atau pull request, tambahkan rujukan dengan menuliskan URL lengkap atau dengan nomor isu atau pull request yang diawali dengan karakter #. Contohnya, Diajukan oleh #987654.
• Mengikuti Kode Etik Komunitas. Menghargai kontributor lain. Misalnya, "Dokumentasi ini sangat jelek" adalah contoh yang tidak membantu dan juga bukan masukan yang sopan.

2 - Berpartisipasi dalam SIG Docs

SIG Docs merupakan salah satu kelompok peminatan khusus (special interest groups) dalam proyek Kubernetes, yang berfokus pada penulisan, pembaruan, dan pemeliharaan dokumentasi untuk Kubernetes secara keseluruhan. Lihatlah SIG Docs dari repositori github komunitas untuk informasi lebih lanjut tentang SIG.

SIG Docs menerima konten dan ulasan dari semua kontributor. Siapa pun dapat membuka pull request (PR), dan siapa pun boleh mengajukan isu tentang konten atau komen pada pull request yang sedang berjalan.

Kamu juga bisa menjadi anggota (member), pengulas (reviewer, atau pemberi persetujuan (approver). Peran tersebut membutuhkan akses dan mensyaratkan tanggung jawab tertentu untuk menyetujui dan melakukan perubahan. Lihatlah keanggotaan-komunitas (community-membership) untuk informasi lebih lanjut tentang cara kerja keanggotaan dalam komunitas Kubernetes.

Selebihnya dari dokumen ini akan menguraikan beberapa cara unik dari fungsi peranan tersebut dalam SIG Docs, yang bertanggung jawab untuk memelihara salah satu aspek yang paling berhadapan dengan publik dalam Kubernetes - situs web dan dokumentasi dari Kubernetes.

Ketua umum (chairperson) SIG Docs

Setiap SIG, termasuk SIG Docs, memilih satu atau lebih anggota SIG untuk bertindak sebagai ketua umum. Mereka merupakan kontak utama antara SIG Docs dan bagian lain dari organisasi Kubernetes. Mereka membutuhkan pengetahuan yang luas tentang struktur proyek Kubernetes secara keseluruhan dan bagaimana SIG Docs bekerja di dalamnya. Lihatlah Kepemimpinan (leadership) untuk daftar ketua umum yang sekarang.

Tim dan automasi dalam SIG Docs

Automasi dalam SIG Docs bergantung pada dua mekanisme berbeda: Tim GitHub dan berkas OWNERS.

Tim GitHub

Terdapat dua kategori tim dalam SIG Docs tim (teams) dalam GitHub:

• @sig-docs-{language}-owners merupakan pemberi persetujuan (approver) dan pemimpin (lead)
• @sig-docs-{language}-reviews merupakan pengulas (reviewer)

Setiap tim dapat direferensikan dengan @name mereka dalam komen GitHub untuk berkomunikasi dengan setiap orang di dalam grup.

Terkadang tim Prow dan GitHub tumpang tindih (overlap) tanpa kecocokan sama persis. Untuk penugasan masalah, pull request, dan untuk mendukung persetujuan PR, otomatisasi menggunakan informasi dari berkas OWNERS.

Berkas OWNERS dan bagian yang utama (front-matter)

Proyek Kubernetes menggunakan perangkat otomatisasi yang disebut prow untuk melakukan automatisasi yang terkait dengan isu dan pull request dalam GitHub. Repositori situs web Kubernetes menggunakan dua buah prow plugin):

• blunderbuss
• approve

Kedua plugin menggunakan berkas OWNERS dan OWNERS_ALIASES dalam level teratas dari repositori GitHub kubernetes/website untuk mengontrol bagaimana prow bekerja di dalam repositori.

Berkas OWNERS berisi daftar orang-orang yang menjadi pengulas dan pemberi persetujuan di dalam SIG Docs. Berkas OWNERS juga bisa terdapat di dalam subdirektori, dan dapat menimpa peranan karena dapat bertindak sebagai pengulas atau pemberi persetujuan berkas untuk subdirektori itu dan apa saja yang ada di dalamnya. Untuk informasi lebih lanjut tentang berkas OWNERS pada umumnya, lihatlah OWNERS.

Selanjutnya, berkas markdown individu dapat menyimpan daftar pengulas dan pemberi persetujuan pada bagian yang utama, baik dengan menyimpan daftar nama pengguna individu GitHub atau grup GitHub.

Kombinasi dari berkas OWNERS dan bagian yang utama dalam berkas markdown menentukan saran kepada pemilik PR yang didapat dari sistem otomatis tentang siapa yang akan meminta ulasan teknis dan ulasan editorial untuk PR mereka.

Cara menggabungkan pekerjaan

Ketika pull request digabungkan ke cabang (branch) yang digunakan untuk mempublikasikan konten, konten itu dipublikasikan di http://kubernetes.io. Untuk memastikan bahwa kualitas konten yang kita terbitkan bermutu tinggi, kita membatasi penggabungan pull request bagi para pemberi persetujuan SIG Docs. Beginilah cara kerjanya.

• Ketika pull request memiliki label lgtm dan approve, tidak memiliki label hold, dan telah lulus semua tes, pull request akan digabungkan secara otomatis.
• Anggota organisasi Kubernetes dan pemberi persetujuan SIG Docs dapat menambahkan komen untuk mencegah penggabungan otomatis dari pull request yang diberikan (dengan menambahkan komen /hold atau menahan komen /lgtm).
• Setiap anggota Kubernetes dapat menambahkan label lgtm dengan menambahkan komen lgtm
• Hanya pemberi persetujuan SIG Docs yang bisa menggabungkan pull request dengan menambahkan komen /approve. Beberapa pemberi persetujuan juga dapat melakukan tugas tambahan seperti PR Wrangler atau Ketua Umum SIG Docs.

Selanjutnya

Untuk informasi lebih lanjut tentang cara berkontribusi pada dokumentasi Kubernetes, lihatlah:

• Berkontribusi konten baru
• Mengulas konten
• Panduan gaya dokumentasi

3 - Dokumentasi Khusus Untuk Translasi Bahasa Indonesia

Panduan khusus untuk bergabung ke komunitas SIG DOC Indonesia dan melakukan kontribusi untuk mentranslasikan dokumentasi Kubernetes ke dalam Bahasa Indonesia.

Manajemen Milestone Tim

Secara umum siklus translasi dokumentasi ke Bahasa Indonesia akan dilakukan 3 kali dalam setahun (sekitar setiap 4 bulan). Untuk menentukan dan mengevaluasi pencapaian atau milestone dalam kurun waktu tersebut jadwal rapat daring reguler tim Bahasa Indonesia dilakukan secara konsisten setiap dua minggu sekali. Dalam agenda rapat ini juga dilakukan pemilihan PR Wrangler untuk dua minggu ke depan. Tugas PR Wrangler tim Bahasa Indonesia serupa dengan PR Wrangler dari proyek upstream.

Target pencapaian atau milestone tim akan dirilis sebagai issue tracking seperti ini pada Kubernetes GitHub Website setiap 4 bulan. Dan bersama dengan informasi PR Wrangler yang dipilih setiap dua minggu, keduanya akan diumumkan di Slack channel #kubernetes-docs-id dari Komunitas Kubernetes.

Cara Memulai Translasi

Untuk menerjemahkan satu halaman Bahasa Inggris ke Bahasa Indonesia, lakukan langkah-langkah berikut ini:

• Check halaman issue di GitHub dan pastikan tidak ada orang lain yang sudah mengklaim halaman kamu dalam daftar periksa atau komentar-komentar sebelumnya.
• Klaim halaman kamu pada issue di GitHub dengan memberikan komentar di bawah dengan nama halaman yang ingin kamu terjemahkan dan ambillah hanya satu halaman dalam satu waktu.
• Fork repo ini, buat terjemahan kamu, dan kirimkan PR (pull request) dengan label language/id
• Setelah dikirim, pengulas akan memberikan komentar dalam beberapa hari, dan tolong untuk menjawab semua komentar. Direkomendasikan juga untuk melakukan squash commit kamu dengan pesan commit yang baik.

Informasi Acuan Untuk Translasi

Tidak ada panduan gaya khusus untuk menulis translasi ke bahasa Indonesia. Namun, secara umum kita dapat mengikuti panduan gaya bahasa Inggris dengan beberapa tambahan untuk kata-kata impor yang dicetak miring.

Harap berkomitmen dengan terjemahan kamu dan pada saat kamu mendapatkan komentar dari pengulas, silahkan atasi sebaik-baiknya. Kami berharap halaman yang diklaim akan diterjemahkan dalam waktu kurang lebih dua minggu. Jika ternyata kamu tidak dapat berkomitmen lagi, beri tahu para pengulas agar mereka dapat meberikan halaman tersebut ke orang lain.

Beberapa acuan tambahan dalam melakukan translasi silahkan lihat informasi berikut ini:

Daftara Glosarium Translasi dari tim SIG DOC Indonesia

Untuk kata-kata selengkapnya silahkan baca glosariumnya disini

KBBI

Konsultasikan dengan KBBI (Kamus Besar Bahasa Indonesia) disini dari Kemendikbud.

RSNI Glosarium dari Ivan Lanin

RSNI Glosarium dapat digunakan untuk memahami bagaimana menerjemahkan berbagai istilah teknis dan khusus Kubernetes.

Panduan Penulisan Source Code

Mengikuti kode asli dari dokumentasi bahasa Inggris

Untuk kenyamanan pemeliharaan, ikuti lebar teks asli dalam kode bahasa Inggris. Dengan kata lain, jika teks asli ditulis dalam baris yang panjang tanpa putus atu baris, maka teks tersebut ditulis panjang dalam satu baris meskipun dalam bahasa Indonesia. Jagalah agar tetap serupa.

Hapus nama reviewer di kode asli bahasa Inggris

Terkadang reviewer ditentukan di bagian atas kode di teks asli Bahasa Inggris. Secara umum, reviewer-reviewer halaman aslinya akan kesulitan untuk meninjau halaman dalam bahasa Indonesia, jadi hapus kode yang terkait dengan informasi reviewer dari metadata kode tersebut.

Panduan Penulisan Kata-kata Translasi

Panduan umum

• Gunakan "kamu" daripada "Anda" sebagai subyek agar lebih bersahabat dengan para pembaca dokumentasi.
• Tulislah miring untuk kata-kata bahasa Inggris yang diimpor jika kamu tidak dapat menemukan kata-kata tersebut dalam bahasa Indonesia. Benar: controller. Salah: controller, controller

Panduan untuk kata-kata API Objek Kubernetes

Gunakan gaya "CamelCase" untuk menulis objek API Kubernetes, lihat daftar lengkapnya di sini. Sebagai contoh:

• Benar: PersistentVolume. Salah: volume persisten, PersistentVolume, persistentVolume
• Benar: Pod. Salah: pod, pod, "pod"

Tips : Biasanya API objek sudah ditulis dalam huruf kapital pada halaman asli bahasa Inggris.

Panduan untuk kata-kata yang sama dengan API Objek Kubernetes

Ada beberapa kata-kata yang serupa dengan nama API objek dari Kubernetes dan dapat mengacu ke arti yang lebih umum (tidak selalu dalam konteks Kubernetes). Sebagai contoh: service, container, node , dan lain sebagainya. Kata-kata sebaiknya ditranslasikan ke Bahasa Indonesia sebagai contoh service menjadi layanan, container menjadi kontainer.

Tips : Biasanya kata-kata yang mengacu ke arti yang lebih umum sudah tidak ditulis dalam huruf kapital pada halaman asli bahasa Inggris.

Panduan untuk "Feature Gate" Kubernetes

Istilah feature gate Kubernetes tidak perlu diterjemahkan ke dalam bahasa Indonesia dan tetap dipertahankan dalam bentuk aslinya.

Contoh dari functional gate adalah sebagai berikut:

• Akselerator
• AdvancedAuditing
• AffinityInAnnotations
• AllowExtTrafficLocalEndpoints
• ...

Glosarium Indonesia