Berkontribusi Pada Dokumen Web MDN

MDN Web Docs telah mendokumentasikan platform web selama lebih dari dua belas tahun dan sekarang merupakan upaya lintas platform dengan kontribusi dan Dewan Penasihat dengan anggota dari Google, Microsoft dan Samsung serta mereka yang mewakili Firefox. Sesuatu yang mendasar bagi MDN adalah bahwa ini adalah upaya komunitas yang besar, dengan komunitas web membantu membuat dan memelihara dokumentasi. Dalam artikel ini, saya akan memberi Anda beberapa petunjuk tentang tempat-tempat di mana Anda dapat membantu berkontribusi pada MDN dan bagaimana tepatnya melakukannya.

Jika Anda belum pernah berkontribusi pada proyek open source sebelumnya, MDN adalah tempat yang brilian untuk memulai. Keterampilan yang dibutuhkan berkisar dari menyalin, menerjemahkan dari bahasa Inggris ke bahasa lain, keterampilan HTML dan CSS untuk membuat Contoh Interaktif, atau minat pada kompatibilitas browser untuk memperbarui data Kompatibilitas Browser. Yang tidak perlu Anda lakukan adalah menulis banyak kode untuk berkontribusi. Ini sangat mudah, dan cara terbaik untuk memberikan kembali kepada komunitas jika Anda pernah menemukan dokumen ini berguna.

Berkontribusi Ke Halaman Dokumentasi

Tempat pertama yang mungkin ingin Anda sumbangkan adalah ke dokumen MDN itu sendiri. MDN adalah wiki, jadi Anda dapat masuk dan mulai membantu dengan mengoreksi atau menambahkan dokumentasi apa pun untuk CSS, HTML, JavaScript, atau bagian lain dari platform web yang dicakup oleh MDN.

Untuk mulai mengedit, Anda harus masuk menggunakan GitHub. Seperti biasa dengan wiki, setiap editor halaman terdaftar, dan bagian ini akan menggunakan nama pengguna GitHub Anda. Jika Anda melihat salah satu halaman di MDN kontributor terdaftar di bagian bawah halaman, gambar di bawah ini menunjukkan kontributor saat ini ke halaman di CSS Grid Layout.

Apa yang Mungkin Anda Edit?

Hal-hal yang mungkin Anda pertimbangkan sebagai editor adalah memperbaiki kesalahan ketik dan kesalahan tata bahasa. Jika Anda seorang korektor dan copyeditor yang baik, maka Anda mungkin dapat meningkatkan keterbacaan dokumen dengan memperbaiki kesalahan ejaan atau kesalahan lain yang Anda temukan.

Anda mungkin juga menemukan kesalahan teknis, atau di suatu tempat spesifikasi telah berubah dan di mana pembaruan atau klarifikasi akan berguna. Dengan sejumlah besar fitur platform web yang dicakup oleh MDN dan tingkat perubahannya, sangat mudah untuk hal-hal menjadi ketinggalan zaman, jika Anda menemukan sesuatu - perbaiki!

Anda mungkin dapat menggunakan beberapa pengetahuan khusus yang Anda miliki untuk menambahkan informasi tambahan. Misalnya, Eric Bailey telah menambahkan bagian Kekhawatiran Aksesibilitas ke banyak halaman. Ini adalah upaya brilian untuk menyoroti hal-hal yang harus kita pikirkan saat menggunakan sesuatu.

Tempat lain yang dapat Anda tambahkan ke halaman adalah dengan menambahkan tautan "Lihat juga". Ini bisa berupa tautan ke bagian lain dari MDN, atau ke sumber daya eksternal. Saat menambahkan sumber daya eksternal, ini harus sangat relevan dengan properti, elemen, atau teknik yang dijelaskan oleh dokumen itu. Kandidat yang baik adalah tutorial yang menunjukkan cara menggunakan fitur itu, sesuatu yang akan memberi pembaca yang mencari informasi langkah berikutnya yang berharga.

Bagaimana Cara Mengedit Dokumen?

Setelah Anda masuk, Anda akan melihat tautan ke Edit pada halaman di MDN, mengklik ini akan membawa Anda ke editor WYSIWYG untuk mengedit konten. Beberapa pengeditan pertama Anda cenderung berupa perubahan kecil, dalam hal ini Anda harus dapat mengikuti hidung Anda dan mengedit teks. Jika Anda melakukan pengeditan ekstensif, ada baiknya melihat panduan gaya terlebih dahulu. Ada juga panduan untuk menggunakan Editor WYSIWYG.

Setelah melakukan pengeditan, Anda dapat Pratinjau dan kemudian Publikasikan. Sebelum menerbitkan, sebaiknya jelaskan apa yang Anda tambahkan dan mengapa menggunakan kolom Komentar Revisi.

Terjemahan Bahasa

Kita yang menggunakan bahasa Inggris sebagai bahasa pertama sangat beruntung dalam hal informasi di web, karena bisa mendapatkan hampir semua informasi yang kita inginkan dalam bahasa kita sendiri. Jika Anda dapat menerjemahkan halaman bahasa Inggris ke bahasa lain, maka Anda dapat membantu menerjemahkan MDN Web Docs, membuat semua informasi ini tersedia untuk lebih banyak orang.

Jika Anda mengklik ikon bahasa di halaman mana pun, Anda dapat melihat ke bahasa mana informasi telah diterjemahkan, dan Anda dapat menambahkan terjemahan Anda sendiri dengan mengikuti informasi di halaman Menerjemahkan Halaman MDN.

Contoh Interaktif

Contoh Interaktif di MDN, adalah contoh yang akan Anda lihat di bagian atas banyak halaman MDN, seperti yang ini untuk properti grid-area .

Contoh-contoh ini memungkinkan pengunjung MDN untuk mencoba berbagai nilai untuk properti CSS atau mencoba fungsi JavaScript, langsung di MDN tanpa perlu masuk ke lingkungan pengembangan untuk melakukannya. Proyek untuk menambahkan contoh-contoh ini telah berlangsung selama sekitar satu tahun, Anda dapat membaca tentang proyek dan kemajuan hingga saat ini di pos Membawa Contoh Interaktif ke MDN.

Konten untuk Contoh Interaktif ini disimpan di repositori GitHub Contoh Interaktif. Misalnya, jika Anda ingin mencari contoh untuk area grid, Anda akan menemukannya di repo itu di bawah live-examples/css-examples/grid . Di bawah folder itu, Anda akan menemukan dua file untuk grid-area , sebuah file HTML dan CSS.

grid-area.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.area.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

Contoh Interaktif hanyalah demo kecil, yang menggunakan beberapa kelas dan ID standar agar kerangka kerja dapat mengambil contoh dan menjadikannya interaktif, di mana nilainya dapat diubah oleh pengunjung halaman yang ingin melihat dengan cepat bagaimana itu bekerja. Untuk menambah atau mengedit Contoh Interaktif, pertama-tama fork repo Contoh Interaktif, klon ke mesin Anda dan ikuti instruksi pada halaman Berkontribusi untuk menginstal paket yang diperlukan dari npm dan dapat membuat dan menguji contoh secara lokal.

Kemudian buat cabang dan edit atau buat contoh baru Anda. Setelah Anda puas, kirim Permintaan Tarik ke repo Contoh Interaktif untuk meminta contoh Anda ditinjau. Untuk menjaga agar contoh tetap konsisten, ulasan cukup rumit tetapi harus menunjukkan perubahan yang perlu Anda buat dengan cara yang jelas, sehingga Anda dapat memperbarui contoh Anda dan menyetujuinya, digabungkan, dan ditambahkan ke halaman MDN.

Dengan hampir semua CSS sekarang tercakup (selain contoh JavaScript), MDN sekarang mencari bantuan untuk membuat contoh HTML. Ada petunjuk tentang cara memulai dalam posting di Forum Wacana MDN. Lihat posting itu karena memberikan tautan ke dokumen Google yang dapat Anda gunakan untuk menunjukkan bahwa Anda sedang mengerjakan contoh tertentu, serta beberapa informasi berguna lainnya.

Contoh Interaktif sangat berguna bagi orang yang menjelajahi platform web, jadi menambahkan proyek adalah cara terbaik untuk berkontribusi. Berkontribusi pada contoh CSS atau HTML membutuhkan pengetahuan tentang CSS dan HTML, ditambah kemampuan untuk memikirkan demonstrasi yang jelas. Poin terakhir ini sering kali merupakan bagian tersulit, saya telah membuat banyak Contoh Interaktif CSS dan menghabiskan lebih banyak waktu untuk memikirkan contoh terbaik untuk setiap properti daripada menulis kode.

Data Kompatibilitas Peramban

Cukup baru-baru ini data kompatibilitas browser yang terdaftar di Halaman MDN telah mulai diperbarui melalui Proyek Kompatibilitas Browser. Proyek ini mengembangkan data kompatibilitas browser dalam format JSON, yang dapat menampilkan tabel kompatibilitas pada MDN tetapi juga menjadi data yang berguna untuk tujuan lain.

Data Kompatibilitas Browser ada di GitHub, dan jika Anda menemukan halaman yang memiliki informasi yang salah atau masih menggunakan tabel lama, Anda dapat mengirimkan Permintaan Tarik. Repositori berisi informasi kontribusi, namun, cara termudah untuk memulai adalah mengedit contoh yang ada. Saya baru-baru ini memperbarui informasi untuk properti CSS shape-outside . Properti sudah memiliki beberapa data dalam format baru, tetapi tidak lengkap dan salah.

Untuk mengedit data ini, saya terlebih dahulu melakukan fork pada Data Compat Browser sehingga saya memiliki fork sendiri. Saya kemudian mengkloningnya ke mesin saya dan membuat cabang baru untuk membuat perubahan saya.

Setelah saya memiliki cabang baru, saya menemukan file JSON untuk shape-outside dan dapat melakukan pengeditan. Saya sudah memiliki ide bagus tentang dukungan browser untuk properti; Saya juga menggunakan contoh langsung pada halaman MDN bentuk-luar untuk menguji untuk melihat dukungan ketika saya tidak yakin. Oleh karena itu melakukan pengeditan adalah kasus bekerja melalui file, memeriksa nomor versi yang terdaftar untuk dukungan properti dan memperbarui yang salah.

Karena file dalam format JSON cukup mudah untuk diedit di editor teks apa pun. File .editorconfig menjelaskan aturan pemformatan sederhana untuk dokumen-dokumen ini. Ada juga beberapa tips bermanfaat dalam daftar periksa ini.

Setelah Anda melakukan pengeditan, Anda dapat melakukan perubahan Anda, mendorong cabang Anda ke fork Anda dan kemudian membuat Permintaan Tarik ke repositori Data Compat Browser. Sepertinya, seperti contoh langsung, peninjau akan memiliki beberapa perubahan untuk Anda buat. Dalam PR saya untuk data Bentuk, saya memiliki beberapa kesalahan dalam cara saya menandai data dan perlu membuat beberapa perubahan pada tautan. Ini mudah dibuat, dan kemudian PR saya digabungkan.

Memulai

Anda dapat memulai hanya dengan memilih sesuatu untuk ditambahkan dan mulai mengerjakannya dalam banyak kasus. Jika Anda memiliki pertanyaan atau memerlukan bantuan dengan semua ini, maka forum Wacana MDN adalah tempat yang baik untuk memposting. MDN adalah tempat saya mencari informasi, tempat saya mengirim pengembang baru dan pengembang berpengalaman, dan kekuatannya adalah kenyataan bahwa kita semua dapat bekerja untuk membuatnya lebih baik.

Jika Anda belum pernah membuat Permintaan Tarik pada sebuah proyek sebelumnya, ini adalah tempat yang sangat ramah untuk membuat PR pertama itu dan, seperti yang saya harap telah saya tunjukkan, ada cara untuk berkontribusi yang tidak memerlukan penulisan kode sama sekali. Keterampilan yang sangat berharga untuk proyek dokumentasi apa pun adalah keterampilan menulis, mengedit, dan menerjemahkan karena keterampilan ini dapat membantu membuat dokumentasi teknis lebih mudah dibaca dan dapat diakses oleh lebih banyak orang di seluruh dunia.