Halaman ini diterjemahkan oleh Cloud Translation API.

Project ESLint

Halaman ini berisi detail proyek penulisan teknis yang diterima untuk Google Season of 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 dalam satu halaman. Meskipun ada {i>heading<i}, {i>subheadings<i}, dan paragraf yang tepat pada halaman, dokumentasi bisa membingungkan. Tidak ada cara untuk menavigasi ke bagian laman tertentu yang menjengkelkan bagi pengguna yang tertarik dengan bagian tertentu. Karena kurangnya organisasi ini, informasi juga bisa tersesat, gagal mencapai tujuannya dan meminta pengguna untuk berusaha lebih keras.

Namun, masalah ini dapat diselesaikan 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 usang atau tidak lengkap). Saya kemudian berencana membuat Arsitektur Informasi (IA) untuk mengungkap jaringan pengetahuan. Dengan begitu, kami dapat mengelompokkan informasi menurut berbagai topik dan menemukan tautan 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 direferensikan silang dalam Markdown. Hasilnya, akan ada versi dokumentasi konfigurasi yang tertata lebih baik, yang lebih mudah dinavigasi dan dipahami.

Motivasi Terlepas dari fakta bahwa saya telah 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 dapat mengacaukan seluruh kode. Menurut saya, akan lebih baik jika Anda melakukan pengujian kode dan mengidentifikasi error, lalu saya mengetahui istilah "linting". Saya belum menggunakan software lint dengan tepat, 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 coding dan persyaratan programmer dengan cara yang lebih baik. Selain itu, gelar pascasarjana saya di bidang Komunikasi Teknis dan Profesional membuat saya menjadi penasihat pengguna, yang berusaha membuat hidup lebih mudah bagi orang-orang. Keterampilan dan keahlian saya akan berfungsi sebagai kombinasi yang baik untuk proyek ini, yang memberi nilai tambah ke dokumentasi ESLint.

Tujuan Tujuan keseluruhan proyek ini adalah untuk memastikan bahwa dokumentasi pada halaman konfigurasi ESLint mudah dipahami dan tidak membingungkan pengguna. Untuk keberhasilan project, 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 aliran informasi - Meningkatkan Arsitektur Informasi untuk mengatur ulang dokumentasi - Mengidentifikasi link dan referensi antara bagian konten yang berbeda - 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 pada satu atau dua aspek pada waktu tertentu. Oleh karena itu, penting bagi pengguna untuk dipandu ke topik yang mereka minati, agar dapat memberikan solusi secara efisien. Status dokumentasi konfigurasi untuk ESLint saat ini berisi banyak informasi berguna tetapi diatur sedemikian rupa sehingga dapat membuat pengguna merasa kewalahan, frustrasi, dan kehilangan. Misalnya, jika seseorang tertarik untuk mempelajari penggunaan plugin pihak ketiga dalam ESLint, mereka harus men-scroll ke bawah, mempelajari diskusi tentang menentukan parser, lingkungan, dan global. Seluruh praktik ini melelahkan bagi pengguna dan bisa membuat mereka meninggalkan situs web. Demikian juga, jika pengguna berada di 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 segera diperhatikan karena kualitas dokumentasi apa pun, terlepas dari seberapa baik penyusunannya, bergantung pada kegunaannya. Saya mengusulkan solusi untuk masalah ini, dan masalah terkait lainnya, dalam diskusi berikutnya.

Audit Konten Langkah pertama dalam proses pengaturan ulang dokumentasi konfigurasi adalah melakukan audit konten yang komprehensif. Audit akan bertujuan mengidentifikasi beberapa masalah utama seperti konten usang, duplikasi, konten yang tidak ada, dll. Spreadsheet audit konten yang dibuat sebagai hasilnya akan dibagikan kepada tim pengelolaan dan dokumentasi untuk mendapatkan masukan. Langkah ini akan membantu Anda menghasilkan strategi baru untuk menyusun dan mempresentasikan dokumentasi.

Membuat Arsitektur Informasi Untuk memahami jaringan pengetahuan atau aliran informasi dalam dokumentasi konfigurasi, pembuatan arsitektur informasi (IA) sangat bermanfaat. Temuan audit konten akan berfungsi sebagai fondasi yang baik untuk memahami dan mengembangkan aliran informasi. Versi IA yang ditingkatkan kemudian 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 tautan dan percabangan di antara berbagai bagian dokumentasi, sehingga menciptakan jaringan yang efisien. Misalnya, konten di bagian "Mengonfigurasi Aturan" dapat diikuti dengan link yang mengarah ke "Aturan Penonaktifan dengan Komentar Inline". Link semacam ini juga dapat diidentifikasi, sehingga menciptakan hubungan di antara bagian-bagian dokumentasi yang berbeda.

Audit Daftar Isi Audit konten dan IA akan memberikan informasi yang memadai untuk membuat daftar isi yang mendetail dengan link yang mengarah ke bagian dan subbagian dokumentasi tertentu. Membuat file terpisah untuk setiap bagian dan menambahkan referensi yang sesuai ke bagian lain dapat menambah nilai pada seluruh kumpulan dokumen. Daftar isi dapat dibuat untuk pengguna yang tiba di 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 segala sesuatunya tetap sederhana dan terorganisir dengan baik. Anda harus sangat berhati-hati untuk memastikan bahwa dokumentasi dapat digunakan kembali karena dokumentasi tersebut mungkin berkembang dan berubah di masa mendatang.

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

- GitHub untuk memastikan kontrol versi dokumentasi

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

10 Juli 2020 - 16 Agustus 2020: Peninjauan dan seleksi 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 tersebut.

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

14 September 2020 - 19 September 2020: Audit konten Untuk memulai project 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 untuk dokumentasi konfigurasi. Saya akan berfokus pada menyajikan jaringan pengetahuan dengan cara yang dapat dipahami. Hal ini akan membantu 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 wawasan yang diperoleh melalui audit konten dan IA, saya kemudian 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.

4 Oktober 2020 - 5 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 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 dalam 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 keakuratan pekerjaan saya. Saya juga akan menambahkan tautan dan referensi antar-bagian, sesuai IA, untuk memastikan bahwa dokumentasi tersebut 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. Langkah ini akan berfungsi sebagai pengiriman draf pertama, dalam bentuk paket lengkap.

1 November 2020 - 05 November 2020: Tinjauan pertama Selama lima hari ini, saya akan membahas draf pertama dengan mentor saya. Saya akan mendapatkan masukan mereka dan mendiskusikan 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 kembali, akurasi, dan fleksibilitas akan berfungsi sebagai titik awal dari fase pengeditan.

13 November 2020 - 15 November 2020: Peninjauan kedua Setelah pengeditan awal selesai, saya akan membahas progresnya 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 timbul dalam proses pengeditan.

16 November 2020 - 19 November 2020: Pengeditan kedua Kemudian, saya akan mendedikasikan periode empat hari untuk mengedit dokumen. Versi yang dihasilkan sebagai hasilnya akan didiskusikan dengan mentor untuk memberi mereka bentuk akhir. Dokumen yang telah selesai di tahap ini akan berada dalam bentuk final, 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 proyek yang terperinci akan dibuat dalam periode lima hari ini. Tujuan, perjuangan, permasalahan, dan solusi yang disajikan akan menjadi bagian dari laporan proyek. Laporan tersebut 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 proyek akan dilakukan melalui pertemuan/diskusi dengan para mentor dan tim terkait.

Selama proyek ini berlangsung, saya akan terus berkonsultasi dengan para mentor untuk mendapatkan masukan mereka yang berharga. 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 dalam 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 pernah bekerja sebagai Sub-Editor untuk publikasi online (Global Village Space) dan sebagai Communications Magang untuk Duke Forge di Duke University. Selain itu, saya juga memiliki minat pada penulisan kreatif.