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
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.
- 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.
- Deskripsikan isu atau saran untuk peningkatan kualitas. Sediakan detail sebanyak mungkin yang kamu bisa.
- 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):
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:
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.
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
Inggris | Tipe Kata | Indonesia | Sumber | Contoh Kalimat |
---|
cluster | | klaster | | |
container | | kontainer | | |
node | kata benda | node | | |
file | | berkas | | |
service | kata benda | layanan | | |
set | | sekumpulan | | |
resource | | sumber daya | | |
default | | bawaan atau standar (tergantung context) | | Secara bawaan, ...; Pada konfigurasi dan instalasi standar, ... |
deploy | | menggelar | | |
image | | image | | |
request | | permintaan | | |
object | kata benda | objek | https://kbbi.web.id/objek | |
command | | perintah | https://kbbi.web.id/perintah | |
view | | tampilan | | |
support | | tersedia atau dukungan (tergantung konteks) | "This feature is supported on version X; Fitur ini tersedia pada versi X; Supported by community; Didukung oleh komunitas" | |
release | kata benda | rilis | https://kbbi.web.id/rilis | |
tool | | perangkat | | |
deployment | | penggelaran | | |
client | | klien | | |
reference | | rujukan | | |
update | | pembaruan | | The latest update... ; Pembaruan terkini... |
state | | state | | |
task | | task | | |
certificate | | sertifikat | | |
install | | instalasi | https://kbbi.web.id/instalasi | |
scale | | skala | | |
process | kata kerja | memproses | https://kbbi.web.id/proses | |
replica | kata benda | replika | https://kbbi.web.id/replika | |
flag | | tanda, parameter, argumen | | |
event | | event | | |