Halaman ini diterjemahkan oleh Cloud Translation API.

Project ESLint

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

Ringkasan project

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

Project description

Abstrak

Tujuan project ini adalah untuk menyusun ulang dokumentasi konfigurasi untuk ESLint dan membuat arsitektur informasi yang efektif. Ini akan membuat navigasi menjadi lebih mudah dan juga meningkatkan kegunaan dan kegunaan dokumentasi.

Ringkasan Project Dokumentasi konfigurasi ESLint (https://eslint.org/docs/user-guide/configuring), dalam status saat ini, memberikan banyak informasi di satu halaman. Meskipun terdapat judul, subjudul, dan paragraf yang sesuai di halaman, dokumentasi ini dapat menjadi terlalu banyak. Tidak ada cara untuk membuka bagian tertentu di halaman, yang membuat pengguna yang tertarik dengan bagian tertentu merasa frustrasi. Informasi, karena kurangnya pengaturan ini, juga dapat hilang, gagal memenuhi tujuannya, dan meminta pengguna untuk melakukan upaya tambahan.

Namun, masalah ini dapat diatasi dengan serangkaian langkah cermat. Saya mengusulkan audit konten sebagai langkah pertama dalam reorganisasi ini. Audit konten tidak hanya akan membantu mengidentifikasi masalah dalam penyajian informasi, tetapi juga menyoroti kekurangan konten itu sendiri (misalnya, informasi yang sudah tidak berlaku atau tidak lengkap). Kemudian, saya berencana membuat Arsitektur Informasi (IA) untuk mengungkap jaringan pengetahuan. Hal ini akan memungkinkan kami mengelompokkan informasi menurut berbagai topik dan menemukan link antara berbagai topik yang terkait erat. Insight yang diperoleh melalui dua praktik ini kemudian akan digunakan untuk membagi dokumentasi satu halaman menjadi beberapa halaman. Seluruh paket kemudian dapat ditautkan dan dirujuk silang dalam Markdown. Akibatnya, akan ada versi dokumentasi konfigurasi yang lebih terorganisir, yang lebih mudah dijelajahi dan dipahami.

Motivasi Meskipun saya telah menggunakan software open source selama beberapa waktu, pemahaman saya tentang istilah ini masih cukup baru, mirip dengan pengetahuan saya tentang software Linting. Ketika saya mulai belajar Python (melalui edX), saya bertanya-tanya bagaimana kesalahan kecil dapat mengacaukan seluruh kode. Saya pikir akan lebih baik jika kode Anda diuji, dan error Anda diidentifikasi, lalu saya mengetahui istilah “linting”. Saya belum menggunakan software linting dengan tepat, tetapi saya yakin hal ini akan mempermudah hidup saya di masa mendatang.

Dengan latar belakang saya di bidang Teknik Elektro dan beberapa pengalaman dalam pemrograman, saya dapat memahami masalah coding dan persyaratan programmer dengan lebih baik. Selain itu, gelar sarjana saya dalam Komunikasi Teknis dan Profesional membuat saya menjadi pendukung pengguna, yang berusaha mempermudah hidup orang-orang. Keterampilan dan keahlian saya akan berfungsi sebagai kombinasi yang baik untuk project ini, sehingga menambah nilai pada dokumentasi ESLint.

Tujuan Tujuan utama project ini adalah untuk memastikan bahwa dokumentasi di halaman konfigurasi ESLint mudah dipahami dan tidak membebani pengguna. Penting bagi keberhasilan project bahwa navigasi melalui konten menjadi mudah dan bebas dari semua kerumitan. Tujuan penting dari project ini adalah sebagai berikut. - Melakukan audit konten yang komprehensif - Membuat Arsitektur Informasi untuk memahami alur informasi - Meningkatkan Arsitektur Informasi untuk mengatur ulang dokumentasi - Mengidentifikasi link dan referensi di antara berbagai bagian konten - Menulis ulang/Mengedit bagian dokumentasi, jika diperlukan untuk memenuhi persyaratan konfigurasi ulang

- Pastikan konten fleksibel dan dapat digunakan kembali

Deskripsi Project Konfigurasi ESLint adalah fitur penting yang membuat ESLint dapat disesuaikan. Pengguna yang tertarik dengan konfigurasi pasti akan tertarik dengan satu atau dua aspek pada waktu tertentu. Oleh karena itu, penting bagi pengguna untuk diarahkan ke topik tertentu yang mereka minati, sehingga memberikan solusi kepada mereka dengan cara yang efisien. Saat ini, dokumentasi konfigurasi untuk ESLint berisi banyak informasi berguna, tetapi disusun dengan cara yang dapat membuat pengguna merasa kewalahan, frustrasi, dan bingung. Misalnya, jika seseorang tertarik untuk mempelajari penggunaan plugin pihak ketiga di ESLint, dia harus men-scroll ke bawah, melalui diskusi tentang menentukan parser, lingkungan, dan global. Seluruh proses ini melelahkan bagi pengguna dan dapat membuat mereka meninggalkan situs. Demikian pula, jika pengguna berada di bagian tengah halaman dan ingin membuka bagian tertentu atau hanya melihat topik serupa, hal ini tidak akan mudah bagi mereka, karena tidak ada bantuan yang diberikan kepada pengguna. Masalah ini perlu segera ditangani karena kualitas dokumentasi apa pun, tidak peduli seberapa baik drafnya, bergantung pada kegunaannya. Saya mengusulkan solusi untuk masalah ini, dan masalah terkait lainnya, dalam diskusi berikut.

Audit Konten Langkah pertama dalam proses penyusunan ulang dokumentasi konfigurasi adalah melakukan audit konten yang komprehensif. Audit ini 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 masukan mereka. Hal ini akan membantu dalam merumuskan strategi baru untuk menyusun dan menyajikan dokumentasi.

Membuat Arsitektur Informasi Untuk memahami jaringan pengetahuan atau alur informasi dalam dokumentasi konfigurasi, pembuatan arsitektur informasi (IA) dapat bermanfaat. Temuan audit konten akan berfungsi sebagai dasar yang baik untuk memahami dan mengembangkan aliran informasi. Kemudian, versi IA yang lebih baik akan dibuat untuk mengatur dan menyajikan dokumentasi dengan cara yang lebih baik. IA yang ditingkatkan ini tidak hanya akan menyusun ulang konten saat ini, tetapi juga mengidentifikasi link dan cabang di antara berbagai bagian dokumentasi, sehingga menciptakan jaringan yang efisien. Misalnya, konten tentang “Mengonfigurasi Aturan” dapat diikuti dengan link yang mengarah ke “Menonaktifkan Aturan dengan Komentar Inline”. Link lain seperti itu juga dapat diidentifikasi, sehingga menciptakan hubungan antara berbagai bagian dokumentasi.

Daftar Isi Audit konten dan IA akan memberikan informasi yang memadai untuk membuat daftar isi mendetail dengan link yang mengarah ke bagian dan subbagian tertentu dalam 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, adalah yang digunakan oleh Prettier (https://prettier.io/docs/en/index.html) untuk mengatur dokumentasi.

Semua dokumentasi akan dibuat menggunakan Markdown agar tetap sederhana dan teratur. Anda harus sangat berhati-hati untuk memastikan bahwa dokumentasi tersebut dapat digunakan kembali karena mungkin saja berkembang dan berubah di masa mendatang.

Alat yang Dapat Digunakan Beberapa alat penting yang dapat berguna saat mengerjakan project 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

Pencapaian Dari pengiriman proposal hingga penyelesaian project, pencapaian sementara berikut akan memastikan bahwa project selesai tepat waktu, dengan mempertahankan alur yang tepat dalam prosesnya.

10 Juli 2020 - 16 Agustus 2020: Peninjauan dan pemilihan proposal Saya akan membaca 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: Pengenalan komunitas Selama periode pengenalan komunitas, saya akan meningkatkan kualitas proposal saya sesuai dengan diskusi dengan mentor dan tim terkait. Saya juga akan mengedit tujuan dan {i>milestone<i} jika diperlukan. Selain itu, saya akan memastikan untuk membuat daftar alat yang kemudian akan digunakan untuk mengerjakan project.

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

20 September 2020 - 25 September 2020: Arsitektur Informasi (IA) Setelah audit konten, saya akan membuat IA dokumentasi konfigurasi. Saya akan fokus untuk menyajikan jaringan pengetahuan dengan cara yang dapat dipahami. Hal ini kemudian akan membantu dalam melakukan peningkatan pada alur informasi.

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

01 Oktober 2020 - 03 Oktober 2020: Peta akhir Dengan bantuan insight yang diperoleh melalui audit konten dan IA, saya akan membuat peta akhir yang akan diterapkan dalam dokumentasi konfigurasi yang disusun ulang. Peta komprehensif ini akan berisi daftar isi, hierarki topik, dan daftar link serta referensi silang antarbagian dokumentasi.

04 Oktober 2020 - 05 Oktober 2020: Diskusi Pada tahap ini, yaitu sebelum mengedit dokumentasi, saya akan mempresentasikan temuan dan rencana saya kepada mentor dan tim terkait. Masukan mereka akan membantu meningkatkan kualitas rencana dan melakukan perubahan jika diperlukan.

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

21 Oktober 2020 - 25 Oktober 2020: Koreksi dan link Pada fase ini, saya akan meninjau pekerjaan saya sendiri untuk menghilangkan kesalahan tata bahasa dan struktur serta memeriksa kembali akurasi pekerjaan saya. Saya juga akan menambahkan link dan referensi di antara bagian, sesuai dengan IA, untuk memastikan bahwa dokumentasi mengikuti peta pengetahuan yang dibuat sebelumnya.

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

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

06 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 kembali, akurasi, dan fleksibilitas akan menjadi fokus fase pengeditan.

13 November 2020 - 15 November 2020: Peninjauan kedua Setelah pengeditan awal selesai, saya akan membahas progresnya dengan mentor 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 Saya akan menggunakan waktu empat hari untuk mengedit dokumen. Versi yang dihasilkan sebagai hasilnya akan didiskusikan dengan mentor untuk memberikan bentuk akhir. Setelah fase ini selesai, dokumen 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 project Laporan mendetail tentang project akan dibuat dalam periode lima hari ini. Tujuan, perjuangan, isu, dan solusi yang disajikan akan menjadi bagian dari laporan proyek. Laporan ini akan dibagikan kepada mentor untuk mendapatkan masukan.

29 November 2020 - 30 November 2020: Pengiriman akhir Project, beserta semua file, dan laporan project akan dikirimkan kepada mentor. Peninjauan seluruh project akan dilakukan melalui rapat/diskusi dengan mentor dan tim yang terkait.

Selama project berlangsung, saya akan terus berkonsultasi dengan mentor untuk mendapatkan masukan berharga dari mereka. Semua pencapaian ini dapat diubah berdasarkan diskusi dengan mentor dalam periode ikatan komunitas dan peninjauan proposal.

Tentang Saya Saya memiliki gelar sarjana di bidang Teknik Elektro dan gelar pascasarjana di bidang Komunikasi Teknis 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 telah bekerja sebagai Sub-Editor untuk publikasi online (Global Village Space) dan sebagai Intern Komunikasi untuk Duke Forge di Duke University. Selain itu, saya juga memiliki minat dalam menulis kreatif.