Berkontribusi ke Dokumentasi Kubernetes

Jika kamu ingin membantu dengan berkontribusi ke dokumentasi atau situs web Kubernetes, kami dengan senang hati menerima bantuan kamu! Siapapun bisa berkontribusi, baik kamu yang masih baru atau sudah lama di proyek ini, maupun jika kamu adalah seorang developer, seorang pengguna, atau bahkan seorang yang tidak tahan melihat saltik (typo)!

Untuk informasi mengenai isi dan gaya (penulisan) dokumentasi Kubernetes, lihat ikhtisar gaya penulisan dokumentasi.

Jenis-jenis kontributor dokumentasi

• Seorang member dari organisasi Kubernetes yang telah menandatangani CLA dan berkontribusi waktu dan usahanya untuk proyek ini. Lihat Keanggotaan komunitas untuk kriteria spesifik untuk keanggotaan.
• Seorang SIG Docs reviewer adalah seorang anggota organisasi Kubernetes yang telah menunjukkan ketertarikannya untuk memeriksa pull request dokumentasi dan telah ditambahkan ke dalam grup GitHub yang sesuai dan berkas-berkas OWNERS di dalam repositori GitHub, oleh seorang SIG Docs Approver.
• Seorang SIG Docs approver adalah seorang anggota yang memiliki predikat yang baik dan telah menunjukkan komitmen berkelanjutan terhadap proyek ini. Seorang approver dapat melakukan merge terhadap pull request dan mempublikasi konten atas nama organisasi Kubernetes. Para approver juga dapat mewakili SIG Docs dalam komunitas Kubernetes yang lebih besar. Beberapa tugas seorang SIG Docs approver, seperti mengkoordinasi sebuah perilisan, membutuhkan komitmen waktu yang signifikan.

Cara-cara untuk berkontribusi ke dokumentasi

Daftar ini dibagi menjadi hal-hal yang dapat dilakukan oleh siapapun, hal-hal yang dapat dilakukan oleh anggota-anggota organisasi Kubernetes, dan hal-hal yang memerlukan tingkat akses yang lebih tinggi serta pengetahuan terhadap proses-proses SIG Docs. Berkontribusi secara konsisten dari waktu ke waktu dapat membantumu mengerti beberapa peralatan dan keputusan organisasi yang telah dibuat.

Daftar ini bukanlah daftar lengkap mengenai cara-cara kamu dapat berkontribusi terhadap dokumentasi Kubernetes, tetapi daftar ini dapat membantumu memulainya.

• Siapapun
  • Membuka issue untuk ditindaklanjuti
• Member
  • Memutakhirkan dokumentasi yang sudah ada
  • Menyampaikan ide-ide untuk pembaruan di Slack atau [milis SIG docs]SIG docs mailing list
  • Meningkatkan aksesibilitas dokumentasi
  • Memberikan umpan balik yang tidak memikat terhadap PR-PR
  • Menulis blog atau studi kasus
• Reviewer
  • Mendokumentasikan fitur-fitur baru
  • Menyortir dan mengkategorisasi masalah-masalah
  • Memeriksa PR-PR
  • Membuat diagram-diagram, aset grafis, dan screencast atau video yang dapat di-embed
  • Lokalisasi/penerjemahan
  • Berkontribusi pada repositori-repositori lain sebagai seorang wakil dokumentasi
  • Menyunting user-facing strings di dalam kode
  • Memutakhirkan komentar-komentar pada kode, Godoc
• Approver
  • Mempublikasi konten kontributor dengan menyetujui dan melakukan merge terhadap PR-PR
  • Berpartisipasi di dalam sebuah tim rilis Kubernetes sebagai seorang wakil dokumentasi
  • Mengusulkan pemutakhiran terhadap petunjuk gaya penulisan
  • Mengusulkan pemutakhiran terhadap test-test dokumentasi
  • Mengusulkan pemutakhiran terhadap situs web Kubernetes atau peralatan lainnya

Cara-cara tambahan untuk berkontribusi

• Untuk berkontribusi ke komunitas Kubernetes melalui forum-forum daring seperti Twitter atau Stack Overflow, atau mengetahui tentang pertemuan komunitas (meetup) lokal dan acara-acara Kubernetes, kunjungi situs komunitas Kubernetes.
• Untuk mulai berkontribusi ke pengembangan fitur, baca cheatseet kontributor.
• Untuk kontribusi khusus ke halaman Bahasa Indonesia, baca 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 https://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 menerjemahkan 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:

• Periksa 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, silakan 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 silakan lihat informasi berikut ini:

Daftar Glosarium Translasi dari tim SIG DOC Indonesia

Untuk kata-kata selengkapnya silakan baca glosariumnya di sini.

KBBI

Konsultasikan dengan situs KBBI (Kamus Besar Bahasa Indonesia) di sini atau situs dari Kemendikbud di sini.

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 satu baris, maka teks tersebut ditulis panjang dalam satu baris meskipun dalam bahasa Indonesia. Jagalah agar tetap serupa.

Hapus nama pengulas di kode asli bahasa Inggris

Terkadang pengulas ditentukan di bagian atas kode di teks asli Bahasa Inggris. Secara umum, pengulas-pengulas halaman aslinya akan kesulitan untuk meninjau halaman dalam bahasa Indonesia, jadi hapus kode yang terkait dengan informasi pengulas 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.
• Selalu rujuk setiap istilah teknis saat pertama kali disebutkan dalam dokumen ke glosarium.
• Gunakan kalimat aktif bila memungkinkan.
  • ✅ Benar: "Pod menjalankan satu atau lebih kontainer."
  • ❌ Salah: "Sebuah Pod menjalankan satu atau lebih kontainer." (terlalu kaku)
• Jangan menerjemahkan perintah CLI atau keluaran perintah CLI (misalnya, kubectl get pods harus tetap dalam bahasa Inggris).
• Ikuti terjemahan di Glosarium Indonesia.

Panduan untuk kata-kata API Objek Kubernetes

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

• PersistentVolume

  • ✅ Benar: PersistentVolume.
  • ❌ Salah: volume persisten, PersistentVolume, persistentVolume.

• Pod

  • ✅ 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 diterjemahkan 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 feature gate adalah sebagai berikut:

• AllowUnsafeMalformedObjectDeletion
• AnonymousAuthConfigurableEndpoints
• APIResponseCompression
• ...

Glosarium Indonesia