Halaman ini berisi detail proyek penulisan teknis yang diterima untuk Google Season of Dokumen.
Ringkasan proyek
- Organisasi open source:
- Creative Commons
- Penulis teknis:
- nimishnb
- Nama proyek:
- Panduan Penggunaan Kosakata
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Sinopsis Proyek
Kosakata memiliki potensi besar untuk digunakan sebagai library komponen UI utama untuk pembuatan situs. Yang dibutuhkan adalah panduan cara kerja yang canggih dan mudah dipahami oleh orang awam. Informasi penting developer seperti panduan komponen, spesifikasi penggunaan, dan penyesuaian konfigurasi menjadi bagian penting dari dokumentasi apa pun. Hal ini tidak hanya akan mendorong pengguna yang sudah ada untuk merasakan bagaimana kosakata terus berkembang dan mencapai tonggak pencapaian baru, tetapi juga mendorong penggunaan Kosakata dalam proyek yang relatif lebih baru. Hasil yang diinginkan dari pekerjaan saya sebagai pekerja magang tidak hanya akan melibatkan penulisan panduan sederhana untuk menggunakan komponen yang sudah ada sebelumnya, tetapi juga merancang dan mengembangkan halaman beranda (yang mengarah ke dokumentasi terintegrasi untuk masing-masing bagian) untuk Kosakata, Vue-Kosakata, dan Font.
Rencana Proyek
Masalah: Dokumentasi adalah salah satu alasan utama yang menentukan seberapa sukses library open source tertentu. Pertanyaan utama yang dipikirkan developer saat memilih tech stack yang sesuai untuk membangun aplikasi adalah “Apakah library didokumentasikan dengan baik? Apakah data tersebut dikelola dengan baik? Apakah ada beberapa penggunaan dan dukungan kesalahan yang cukup besar?”. Ini adalah pertanyaan yang harus kita tanyakan pada diri sendiri saat menjalankan ide proyek ini. Dari perspektif software engineering:
Analisis Persyaratan: Ada kebutuhan mendesak untuk memiliki dokumentasi yang ringkas dan terkonsolidasi untuk kebutuhan kita. Kurangnya dokumentasi merugikan perspektif aplikasi open source di masa depan, dan sejauh ini merupakan komponen yang penting dan tidak dapat diabaikan. Menautkan ke dokumentasi ini harus menjadi beranda yang menarik, yang menarik minat orang dalam sekejap. Dokumentasi harus terorganisir dengan baik, sehingga memungkinkan kelancaran aliran data.
Spesifikasi: Bergantung pada persyaratan, spesifikasi dapat ditentukan. Konten dalam dokumentasi dapat dibentuk dari data yang ada di situs netlify CC, beserta beberapa inspirasi dari dokumentasi terkenal seperti semantic-ui, scikit-learn, numpy, bootstrap, dll. Output dari tugas ini adalah halaman landing yang diperlukan dan panduan dokumentasi lengkap.
Beberapa masalah umum yang terkait dengan Kosakata, Vue-Vocabulary, dan Fonts saat ini:
Tidak ada dokumentasi; dan bahkan jika ada, bagian dokumentasi tersebut tersebar di seluruh situs web netlify. Hal ini tidak memungkinkan pengguna, developer, atau kontributor eksternal menggunakan library kami.
Untuk membuka komponen tertentu dan menyalin kode yang sesuai, dibutuhkan klik tambahan. Penelusuran sederhana di Google untuk hal seperti “Tabs component CC Vocabulary” tidak akan menampilkan informasi yang diinginkan. Opsi Penelusuran dalam panduan dokumentasi akan meningkatkan UX secara signifikan.
Deskripsi yang sedikit lebih mendetail secara tekstual untuk komponen, yang menjelaskan detail yang tidak jelas.
Tidak ada opsi jalankan langsung. {i>Live run<i} didukung oleh berbagai situs seperti JSFiddle, yang memungkinkan pengembang untuk merasakan komponen tanpa menjalankan seluruh aplikasi untuk melihat cara kerjanya.
Solusi
Ada beberapa solusi yang dapat dilakukan. Namun, di sini saya akan menyampaikan beberapa solusi, dan menyajikan solusi akhir di bagian kesimpulan:-
= Menggunakan readthedocs readthedocs adalah solusi terkenal untuk menulis dokumentasi bagi library open source. Ini didasarkan pada Sphinx, alat dokumentasi python.
Kelebihan:
- Bentuk pembuatan dokumentasi yang diterima secara luas, yang digunakan oleh organisasi seperti Ethereum (Solidity).
- Dokumentasi terstruktur secara optimal.
- Hosting statis gratis.
Kekurangan:
- Kurangnya kontrol mutlak atas gaya visual.
= Menggunakan Sphinx Sebenarnya kita juga bisa menggunakan sphinx untuk bagian dokumentasi, karena menyediakan fitur yang baik untuk semua tujuan kita.
Kelebihan:
- Alat python paling populer untuk dokumentasi.
- Memiliki dukungan untuk penelusuran dokumentasi juga.
- CSS default dapat diganti dengan CSS khusus; beberapa kontrol atas HTML menggunakan file .rst.
Kekurangan:
- Akan melibatkan pengkodean dalam python dan format teks yang direstrukturisasi (.rst) yang akan merupakan penyimpangan dari bahasa proyek yang disarankan.
= Menggunakan Tema Jekyll Tema Jekyll terintegrasi dalam halaman GitHub, dan ada template yang sudah ada sebelumnya yang dapat disesuaikan berdasarkan kebutuhan kita.
Kelebihan:
- Tema dokumentasi siap pakai untuk semua tujuan.
- CSS dan gaya default dapat diganti dengan CSS dan gaya khusus, juga kontrol atas HTML.
- Menarik CSS Primer default untuk membuat halaman.
- Integrasi yang mudah dengan halaman GitHub.
Kekurangan:
- Mungkin tidak memberikan struktur dokumentasi terbaik.
=Menggunakan halaman GitHub Halaman github standar untuk membuat situs statis (HTML, CSS, JS).
Kelebihan:
- Kontrol penuh atas hampir semua hal yang dimaksud.
- Fleksibilitas maksimum dalam menentukan tata letak, warna, dan gaya.
- Penggunaan komponen Kosakata yang mudah.
- Penyematan cuplikan kode dan link live run dengan mudah.
Kekurangan:
- Mungkin pendekatan yang lebih memakan waktu.
= Menggunakan Haroopad Ini memberikan solusi markdown alternatif.
Kelebihan:
- Akan melibatkan coding yang sangat minim.
- Fokusnya adalah menulis dokumentasi dengan sempurna.
Kekurangan:
- Kurangnya kontrol atas CSS.
- Mungkin mendapat dukungan komunitas terbaik atau tidak.
- Mungkin tidak mendukung MDX.
= Menggunakan MKDocs Ini memberikan solusi markdown alternatif lain.
Kelebihan:
- Akan memerlukan sedikit pengkodean fiddly (lagi).
- Tulis lebih banyak, menggunakan pendekatan Code Less.
Kekurangan:
- Kurangnya kontrol atas CSS.
- Mungkin tidak mendapatkan dukungan komunitas terbaik.
- Menggunakan python; mungkin muncul kebutuhan untuk menjalankan instance Amazon S3 lebih lanjut.
= Menggunakan VueJS +StorybookJS Pendekatan ini umum digunakan di seluruh Vocabulary dan repositori seinduknya.
Kelebihan:
- Tetap berpegang pada teknologi yang dijamin berfungsi dengan baik, mengingat pengalaman kerja sebelumnya.
- Pemahaman tentang code base.
- Tidak ada teknologi kompeten di bidang ini.
Kekurangan:
- Opsi yang lebih sederhana juga dapat tersedia untuk tujuan yang sama.
Kesimpulannya, saya ingin berpikir bahwa pendekatan yang melibatkan pendekatan VueJS+Storybook (HTML,CSS,JS) adalah yang paling sesuai, mengingat saya juga merasa nyaman menggunakannya. Namun, ini juga berarti bahwa kami tidak akan sepenuhnya keluar dari pengembangan aplikasi ini. Penggunaan komponen CC-Vocabulary juga akan cukup mudah. Namun, untuk menentukan struktur dokumentasi, kita harus mempertimbangkan cara kontennya dibagi di antara subjudul dalam dokumentasi readthedocs. Saya terkesan dengan situs Semantic-UI (yang menggunakan StoryBook) karena memiliki tampilan minimalis dan orang dapat dengan mudah mengetahui apa yang mereka inginkan hanya dengan beberapa klik. Selain Semantic-UI, saya juga melihat Desain Material, Primer, Bootstrap, Desain Karbon, dll. untuk digunakan sebagai panduan gaya UI dan sistem desain untuk pekerjaan saya. Kita juga dapat mencari inspirasi tema dokumentasi Jekyll yang sudah siap pakai.