Halaman ini diterjemahkan oleh Cloud Translation API.

Project ESLint

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.

Ringkasan proyek

Organisasi open source:: ESLint
Penulis teknis:: Khawar
Nama proyek:: Mengatur Ulang/Menulis Ulang Dokumentasi Konfigurasi
Durasi proyek:: Durasi standar (3 bulan)

Project description

Abstract

Tujuan dari proyek ini adalah untuk merestrukturisasi dokumentasi konfigurasi untuk ESLint dan membuat arsitektur informasi yang efektif. Hal ini akan membuat navigasi lebih mudah dan juga meningkatkan kegunaan dan kegunaan dokumentasi.

Ringkasan Project Dokumentasi konfigurasi ESLint (https://eslint.org/docs/user-guide/configure), dalam status saat ini, memberikan banyak informasi di satu halaman. Meskipun ada {i>heading<i}, {i>subheading<i}, dan paragraf yang sesuai di halaman, dokumentasi bisa sangat membingungkan. Tidak ada cara untuk menavigasi ke bagian halaman tertentu yang menjengkelkan bagi pengguna yang tertarik dengan bagian tertentu. Karena kurangnya pengaturan ini, informasi juga bisa hilang, gagal memenuhi tujuannya dan meminta pengguna untuk melakukan upaya tambahan.

Namun, masalah tersebut dapat diselesaikan dengan serangkaian langkah cermat. Saya mengusulkan audit konten sebagai langkah pertama dalam penataan ulang ini. Audit konten tidak hanya akan membantu mengidentifikasi masalah dalam penyajian informasi, tetapi juga menyoroti kekurangan konten itu sendiri (misalnya, informasi yang sudah usang atau tidak lengkap). Saya kemudian berencana membuat Arsitektur Informasi (IA) untuk mengungkap jaringan pengetahuan. Dengan begitu, kami dapat mengelompokkan informasi sesuai dengan berbagai topik dan menemukan tautan antara berbagai topik yang terkait erat. Wawasan yang diperoleh melalui kedua praktik ini kemudian akan digunakan untuk membagi dokumentasi satu halaman menjadi beberapa halaman. Seluruh paket kemudian dapat ditautkan dan direferensikan silang dalam Markdown. Hasilnya, akan ada versi dokumentasi konfigurasi yang lebih tertata, yang lebih mudah dinavigasi dan dipahami.

Motivasi Meskipun saya sudah menggunakan software open source cukup lama, pemahaman saya terhadap istilah ini cukup baru, mirip dengan pengetahuan saya tentang software Linting. Ketika saya mulai belajar Python (melalui edX), saya bertanya-tanya bagaimana kesalahan kecil bisa mengacaukan seluruh kode. Menurut saya, akan lebih baik jika kode Anda diuji, dan identifikasi errornya, kemudian saya mengetahui tentang istilah “linting”. Saya belum pernah tepat menggunakan software lint, tetapi saya yakin hal ini akan membuat hidup saya jauh lebih mudah di masa mendatang.

Dengan latar belakang Teknik Elektro dan beberapa pengalaman dalam pemrograman, saya dapat memahami masalah {i>coding<i} dan persyaratan programer dengan cara yang lebih baik. Selain itu, gelar sarjana saya di bidang Komunikasi Teknik dan Profesional membuat saya menjadi advokat pengguna, mencoba membuat hidup lebih mudah bagi orang-orang. Keterampilan dan keahlian saya akan berfungsi sebagai kombinasi yang baik untuk proyek ini, sehingga menambah nilai pada dokumentasi ESLint.

Tujuan Tujuan menyeluruh dari project ini adalah untuk memastikan bahwa dokumentasi pada halaman konfigurasi ESLint mudah dipahami dan tidak membingungkan pengguna. Agar proyek berhasil, navigasi konten harus dibuat mudah dan bebas dari semua kerumitan. Tujuan penting dari proyek ini adalah sebagai berikut. - Melakukan audit konten yang komprehensif - Membuat Arsitektur Informasi untuk memahami alur informasi - Meningkatkan Arsitektur Informasi untuk menata ulang dokumentasi - Mengidentifikasi link dan referensi di antara bagian konten yang berbeda - Menulis ulang/Mengedit bagian dokumentasi, jika perlu untuk memenuhi persyaratan konfigurasi ulang

- Pastikan konten fleksibel dan dapat digunakan kembali

Deskripsi Project Konfigurasi ESLint merupakan fitur penting, yang membuat ESLint dapat disesuaikan. Pengguna yang tertarik dengan konfigurasi pasti akan tertarik dengan satu atau dua aspek pada satu waktu. Oleh karena itu, penting bagi pengguna untuk diarahkan ke topik yang mereka minati secara khusus, sehingga dapat memberikan solusi secara efisien. Status dokumentasi konfigurasi untuk ESLint saat ini berisi banyak informasi yang berguna, tetapi terorganisir dengan cara yang dapat membuat pengguna merasa kewalahan, frustrasi, dan tersesat. Misalnya, jika seseorang tertarik untuk mempelajari penggunaan plugin pihak ketiga di ESLint, mereka harus men-scroll ke bawah, mengikuti diskusi tentang menentukan parser, lingkungan, dan global. Seluruh praktik ini melelahkan bagi pengguna dan bisa membuat mereka meninggalkan situs web. Demikian pula, jika pengguna berada di tengah-tengah halaman dan ingin membuka bagian tertentu atau hanya melihat topik serupa, itu tidak akan menjadi tugas yang mudah bagi mereka, karena tidak ada bantuan seperti itu yang diberikan kepada pengguna. Masalah ini perlu diperhatikan segera karena kualitas dokumentasi, terlepas dari seberapa baik penyusunannya, bergantung pada kegunaannya. Saya mengusulkan solusi untuk masalah ini, dan masalah terkait lainnya, dalam diskusi selanjutnya.

Audit Konten Langkah pertama dalam proses pengaturan ulang dokumentasi konfigurasi adalah melakukan audit konten yang komprehensif. Audit akan bertujuan untuk mengidentifikasi beberapa masalah utama seperti konten usang, duplikasi, konten yang hilang, dll. Spreadsheet audit konten yang dibuat sebagai hasilnya akan dibagikan kepada tim manajemen dan dokumentasi untuk mendapatkan umpan balik mereka. Cara ini akan membantu Anda menghasilkan strategi baru untuk menyusun dan menyajikan dokumentasi.

Membuat Arsitektur Informasi Untuk memahami jaringan pengetahuan atau aliran informasi dalam dokumentasi konfigurasi, pembuatan arsitektur informasi (IA) bisa menjadi sangat bermanfaat. Temuan audit konten akan berfungsi sebagai dasar yang baik untuk memahami dan mengembangkan aliran informasi. Versi IA yang lebih baik kemudian akan dibuat untuk mengatur dan menyajikan dokumentasi dengan cara yang lebih baik. Peningkatan IA ini tidak hanya akan merestrukturisasi konten saat ini, tetapi juga mengidentifikasi tautan dan percabangan di antara berbagai bagian dokumentasi, sehingga menciptakan jaringan yang efisien. Misalnya, konten tentang “Mengonfigurasi Aturan” dapat diikuti dengan link yang mengarah ke “Aturan Penonaktifan dengan Komentar Inline”. Link lain seperti itu juga dapat diidentifikasi, sehingga menciptakan hubungan di antara bagian dokumentasi yang berbeda.

Audit Daftar Isi Audit dan IA akan memberikan informasi yang memadai untuk membuat daftar isi terperinci dengan tautan yang mengarah ke bagian dan subbagian tertentu dari dokumentasi. Membuat file terpisah untuk setiap bagian dan menambahkan referensi yang sesuai ke bagian lain dapat menambah nilai ke seluruh kumpulan dokumen. Daftar isi dapat dibuat untuk pengguna yang membuka dokumentasi konfigurasi, sehingga membantu perjalanan mereka saat berada di situs. Daftar isi dapat mencakup semua judul tingkat pertama dan kedua agar tetap singkat namun komprehensif. Salah satu praktik tersebut, misalnya, digunakan oleh Prettier (https://prettier.io/docs/en/index.html) untuk mengelola dokumentasi.

Semua dokumentasi akan dibuat menggunakan Markdown untuk menjaga agar semuanya tetap sederhana dan terorganisir dengan baik. Kami akan sangat berhati-hati untuk memastikan bahwa dokumentasi tersebut dapat digunakan kembali karena dapat berkembang dan berubah di masa mendatang.

Alat untuk Digunakan Beberapa alat penting yang dapat berguna saat mengerjakan proyek adalah - Draw.io untuk membuat ilustrasi IA sesuai kebutuhan - Atom (atau editor serupa) untuk menulis dan mengedit dokumen dalam Markdown

- GitHub untuk memastikan kontrol versi dokumentasi

{i>Milestone<i} Mulai dari pengajuan proposal hingga penyelesaian proyek, {i>milestone<i} tentatif berikut akan memastikan bahwa proyek selesai tepat waktu, mempertahankan alur yang tepat dalam prosesnya.

10 Juli 2020 - 16 Agustus 2020: Peninjauan dan pemilihan proposal Saya akan mempelajari dokumentasi ESLint dan mengembangkan keterampilan yang diperlukan untuk menyelesaikan project (seperti penulisan Markdown, kolaborasi di GitHub). Saya juga akan berkontribusi pada dokumentasi melalui GitHub dan berinteraksi dengan orang lain untuk mendapatkan pemahaman yang lebih baik tentang dokumentasi.

17 Agustus 2020 - 13 September 2020: Ikatan komunitas Selama periode ikatan komunitas, saya akan menyempurnakan proposal sesuai hasil diskusi dengan mentor dan tim terkait. Saya juga akan mengedit tujuan dan {i>milestone<i} jika diperlukan. Selain itu, saya akan memastikan untuk memilih alat/{i>tool<i} yang akan digunakan untuk mengerjakan proyek.

14 September 2020 - 19 September 2020: Audit konten Untuk memulai proyek ini, saya akan melakukan audit konten komprehensif terhadap dokumentasi konfigurasi. Tujuannya adalah untuk menyoroti masalah terkait konten dan presentasinya.

20 September 2020 - 25 September 2020: Arsitektur Informasi (IA) Setelah audit konten, saya akan membuat IA dokumentasi konfigurasi. Saya akan berfokus pada menyajikan jaringan pengetahuan dengan cara yang dapat dimengerti. Hal ini akan membantu Anda melakukan perbaikan pada aliran informasi.

26 September 2020 - 30 September 2020: Link dan referensi Saya akan menganalisis IA selama fase ini untuk memetakan link dan referensi di antara berbagai bagian dokumentasi. Saya juga akan membuat hierarki dari semua bagian, sehingga meningkatkan IA dalam prosesnya.

1 Oktober 2020 - 3 Oktober 2020: Peta akhir Dengan bantuan insight yang diperoleh melalui audit konten dan IA, saya akan membuat peta akhir untuk diterapkan dalam dokumentasi konfigurasi yang ditata ulang. Peta komprehensif ini akan berisi daftar isi, hierarki topik, dan daftar tautan serta referensi silang antar bagian dokumentasi.

04 Oktober 2020 - 5 Oktober 2020: Diskusi Pada titik ini, yaitu sebelum mengedit dokumentasi, saya akan mempresentasikan temuan dan rencana saya kepada mentor dan tim terkait. Masukan mereka akan membantu menyempurnakan rencana dan membuat perubahan jika diperlukan.

6 Oktober 2020 - 20 Oktober 2020: Menulis ulang dan mengedit Dalam periode ini, saya akan mengedit dan memperbarui bagian dokumen yang memerlukan pekerjaan. Beberapa bagian dari dokumentasi konfigurasi mungkin ditulis ulang atau beberapa hal baru mungkin ditambahkan ke dalamnya. Fokus pada fase ini adalah untuk memastikan bahwa dokumentasi akurat, diperbarui, fleksibel, dan dapat digunakan kembali.

21 Oktober 2020 - 25 Oktober 2020: Koreksi dan tautan Dalam fase ini, saya akan meninjau pekerjaan saya sendiri untuk menghilangkan kesalahan tata bahasa dan struktural dan juga untuk memeriksa ulang pekerjaan saya untuk akurasi. Saya juga akan menambahkan tautan dan referensi antarbagian, sesuai dengan IA, untuk memastikan bahwa dokumentasinya mengikuti peta pengetahuan yang dibuat sebelumnya.

26 Oktober 2020 - 31 Oktober 2020: Versi akhir untuk pengiriman Saya akan menautkan semua file Markdown, membuat daftar isi, dan membagikan draf kepada mentor. Dokumen ini akan berfungsi sebagai pengiriman draf pertama, dalam bentuk paket lengkap.

1 November 2020 - 5 November 2020: Tinjauan pertama Selama lima hari ini, saya akan mendiskusikan draf pertama dengan mentor saya. Saya akan mendapatkan masukan mereka dan mendiskusikan ide-ide saya dengan mereka untuk membuat daftar pengeditan yang perlu dilakukan.

6 November 2020 - 12 November 2020: Pengeditan pertama Dengan bantuan masukan mentor, saya akan mengedit draf pertama dokumentasi. Pengeditan yang sebenarnya akan bergantung pada sifat komentar dan masukan, tetapi tujuan penggunaan ulang, akurasi, dan fleksibilitas akan berfungsi sebagai titik fokus dari fase pengeditan.

13 November 2020 - 15 November 2020: Peninjauan kedua Setelah pengeditan awal selesai, saya akan mendiskusikan kemajuannya dengan mentor saya dan tim terkait, sekali lagi. Diskusi ini akan berfokus pada pengeditan yang dilakukan pada versi pertama dan juga menyoroti masalah lain yang mungkin muncul dalam proses pengeditan.

16 November 2020 - 19 November 2020: Pengeditan kedua Selanjutnya, saya akan mendedikasikan waktu empat hari untuk mengedit dokumen. Sebagai hasilnya, versi-versi yang dihasilkan akan didiskusikan dengan mentor untuk memberi mereka bentuk akhir. Dokumen, pada akhir fase ini, akan berada dalam bentuk akhir, siap diupload ke situs dan repositori GitHub.

20 November 2020 - 23 November 2020: Mengupload di situs Setelah melakukan semua pengeditan yang diperlukan, dokumen akan diupload ke situs. Masalah apa pun yang ditemukan dalam proses ini akan ditangani sebagaimana mestinya karena kami masih memiliki waktu beberapa hari untuk mengerjakan dokumentasi.

24 November 2020 - 28 November 2020: Laporan proyek Laporan terperinci proyek akan dibuat dalam periode lima hari ini. Tujuan, perjuangan, permasalahan, dan solusi yang disajikan akan membentuk bagian dari laporan proyek. Laporan akan dibagikan kepada para mentor untuk mendapatkan masukan.

29 November 2020 - 30 November 2020: Pengiriman akhir Proyek, bersama dengan semua file, dan laporan proyek akan diserahkan kepada mentor. Peninjauan seluruh proyek akan dilakukan melalui pertemuan/diskusi dengan para mentor dan tim terkait.

Sepanjang proyek, saya akan terus berkonsultasi dengan para mentor untuk mendapatkan masukan berharga mereka. Semua pencapaian ini dapat diubah berdasarkan diskusi dengan mentor dalam periode ikatan komunitas dan peninjauan proposal.

Tentang Saya Saya meraih gelar sarjana Teknik Elektro dan S2 dalam bidang Komunikasi Teknik dan Profesional dari North Carolina State University. Saya memiliki pengalaman di bidang penulisan dan pengeditan teknis dan profesional, komunikasi dan pengelolaan konten, studi kegunaan web dan seluler, serta desain petunjuk. Saya pernah bekerja sebagai Sub-Editor untuk publikasi online (Global Village Space) dan sebagai Communications Intern untuk Duke Forge di Duke University. Selain itu, saya juga memiliki minat dalam penulisan kreatif.