Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season 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 Project
Kosakata memiliki potensi besar untuk digunakan sebagai library komponen UI utama dalam pembuatan situs. Yang dibutuhkan adalah panduan cara kerja yang andal dan ramah orang awam. Informasi developer yang penting seperti panduan komponen, spesifikasi penggunaan, dan penyesuaian konfigurasi merupakan 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 baru. Hasil yang diinginkan dari pekerjaan saya sebagai pekerja magang tidak hanya 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-masingnya) untuk Kosakata, Vue-Vocabulary, 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 mereka adalah “Apakah library didokumentasikan dengan baik? Apakah terawat dengan baik? Apakah ia memiliki dukungan penggunaan dan kesalahan yang cukup banyak?”. Inilah pertanyaan yang harus kita tanyakan pada diri sendiri saat menjalankan ide proyek ini. Dari perspektif rekayasa perangkat lunak:
Analisis Persyaratan: Ada kebutuhan utama untuk memiliki dokumentasi yang ringkas dan terkonsolidasi untuk kebutuhan kita. Kurangnya dokumentasi melemahkan perspektif masa depan aplikasi open source, dan sejauh ini merupakan komponen yang penting dan tidak dapat diabaikan. Penautan ke dokumentasi ini harus berupa beranda yang menarik, yang langsung menarik minat orang. Dokumentasi harus terorganisir dengan baik, sehingga memungkinkan aliran yang lancar melaluinya.
Spesifikasi: Bergantung pada persyaratan, spesifikasi dapat ditentukan. Konten dalam dokumentasi dapat dibentuk dari data yang ada di situs web CC, beserta beberapa inspirasi dari dokumentasi terkenal seperti semantic-ui, scikit-learn, numpy, bootstrap, dll. Output dari tugas ini akan berupa halaman landing yang diperlukan dan panduan dokumentasi yang lengkap.
Beberapa masalah umum yang berhubungan dengan Kosakata, Kosakata, dan Font saat ini:
Tidak terdapat dokumentasi; dan bahkan jika ada, sebagian dokumen 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 Google untuk sesuatu seperti “Komponen tab CC Kosakata” tidak akan menampilkan informasi yang diinginkan. Opsi Penelusuran dalam panduan dokumentasi akan meningkatkan UX secara signifikan.
Deskripsi yang sedikit lebih detail secara tekstual untuk komponen, yang menjelaskan detail yang tidak jelas.
Tidak ada opsi live run. Live run didukung oleh berbagai situs seperti JSFiddle, yang memungkinkan developer untuk merasakan komponen tanpa menjalankan seluruh aplikasi untuk melihat cara kerjanya.
Solusi
Ada beberapa solusi yang dapat dilakukan. Namun, saya akan menyinggung beberapa di sini, dan menyajikan solusi akhir saya di bagian kesimpulan:-
= Menggunakan readthedocs readthedocs adalah solusi terkenal untuk menulis dokumentasi bagi library open source. Skrip ini didasarkan pada Sphinx, yakni 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 Secara native kita juga dapat menggunakan sphinx untuk bagian dokumentasi, yang menyediakan fitur yang baik untuk semua tujuan kita.
Kelebihan:
- Alat Python paling populer untuk dokumentasi.
- Mendukung penelusuran dokumentasi juga.
- CSS default dapat diganti dengan CSS kustom; 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 di dalam halaman github, dan terdapat template sebelumnya yang dapat disesuaikan dengan kebutuhan.
Kelebihan:
- Tema dokumentasi siap pakai untuk semua tujuan.
- CSS dan gaya default dapat diganti dengan gaya dan CSS kustom, serta kontrol atas HTML.
- Mengambil CSS Primer default untuk membangun halaman.
- Integrasi mudah dengan halaman GitHub.
Kekurangan:
- Mungkin tidak memberikan penataan dokumentasi terbaik.
=Menggunakan halaman GitHub Halaman github standar untuk membuat situs statis (HTML, CSS, JS).
Kelebihan:
- Kontrol penuh atas hampir semua hal yang bersangkutan.
- Fleksibilitas maksimum dalam menentukan tata letak, warna, dan gaya.
- Penggunaan komponen Kosakata yang mudah.
- Kemudahan penyematan cuplikan kode dan link live run.
Kekurangan:
- Mungkin merupakan pendekatan yang lebih memakan waktu.
= Menggunakan Haroopad Ini memberikan solusi markdown alternatif.
Kelebihan:
- Akan melibatkan sedikit coding fidded.
- Fokusnya adalah menulis dokumentasi dengan sempurna.
Kekurangan:
- Kurangnya kontrol atas CSS.
- Mungkin mendapatkan atau tidak mendapatkan dukungan komunitas terbaik.
- Mungkin tidak mendukung MDX.
= Menggunakan MKDocs Sebagai gantinya, tindakan ini memberikan solusi markdown alternatif lain.
Kelebihan:
- Akan memerlukan sedikit coding fidd (lagi).
- Tulis lebih banyak, menggunakan pendekatan Code Less.
Kekurangan:
- Kurangnya kontrol atas CSS.
- Mungkin tidak memiliki dukungan komunitas terbaik.
- Menggunakan python; kemungkinan muncul lebih lanjut perlunya menjalankan instance Amazon S3.
= 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 yang kompeten di bidang ini.
Kekurangan:
- Opsi yang lebih sederhana mungkin juga ada untuk tujuan yang sama.
Kesimpulannya, saya ingin berpikir bahwa pendekatan yang melibatkan pendekatan VueJS+Storybook (HTML,CSS,JS) sepertinya yang paling sesuai, mengingat saya juga merasa nyaman dengan pendekatan tersebut. Namun, ini juga berarti bahwa kami tidak akan sepenuhnya keluar dari cara kami mengembangkan aplikasi ini. Penggunaan komponen CC-Vocabulary juga akan cukup mudah. Namun, untuk menentukan struktur dokumentasi, kita harus mempertimbangkan bagaimana konten dibagi di antara sub-judul 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 mempelajari Desain Material, Primer, Bootstrap, Desain Karbon, dll. yang akan digunakan sebagai panduan gaya UI dan sistem desain untuk pekerjaan saya. Kita juga dapat mencari inspirasi untuk tema dokumentasi Jekyll yang sudah jadi.