Proyek Creative Commons

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

Ringkasan project

Organisasi open source:
Creative Commons
Penulis teknis:
nimishnb
Nama proyek:
Panduan Penggunaan Kosakata
Durasi project:
Durasi standar (3 bulan)

Project description

Sinopsis Proyek

Kosakata memiliki potensi besar untuk digunakan sebagai library komponen UI utama untuk pembuatan situs. Yang diperlukan adalah panduan cara yang andal namun mudah dipahami oleh orang awam. Informasi penting developer seperti panduan komponen, spesifikasi penggunaan, dan penyesuaian konfigurasi merupakan bagian penting dari dokumentasi apa pun. Hal ini tidak hanya akan mendorong pengguna lama untuk merasakan bagaimana kosakata terus berkembang dan mencapai pencapaian baru, tetapi juga mempromosikan penggunaan Kosakata dalam project yang relatif lebih baru. Hasil yang diharapkan dari masa kerja saya sebagai magang tidak hanya melibatkan penulisan panduan praktis untuk menggunakan komponen yang sudah ada, tetapi juga mendesain dan mengembangkan halaman beranda (yang mengarah ke dokumentasi terintegrasi untuk masing-masing) untuk Vocabulary, Vue-Vocabulary, dan Fonts.

Rencana Project

  1. 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 mem-build aplikasi mereka adalah “Apakah library tersebut didokumentasikan dengan baik? Apakah produk itu terpelihara dengan baik? Apakah memiliki dukungan penggunaan dan error yang cukup besar?”. Inilah pertanyaan yang harus kita tanyakan kepada diri sendiri saat mengerjakan ide project ini. Dari perspektif software engineering:

  2. Analisis Persyaratan: Ada kebutuhan yang mendesak untuk memiliki dokumentasi yang ringkas dan gabungan untuk kebutuhan kita. Kurangnya dokumentasi akan merugikan perspektif aplikasi open source di masa depan, dan sejauh ini merupakan komponen yang penting dan tidak dapat diabaikan. Link ke dokumentasi ini harus berupa halaman beranda yang menarik, yang langsung menarik minat orang. Dokumentasi harus terorganisir dengan baik, sehingga memungkinkan aliran yang lancar di dalamnya.

  3. Spesifikasi: Bergantung pada persyaratan, spesifikasi dapat diputuskan. 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 akan menjadi halaman landing yang diperlukan dan panduan dokumentasi lengkap.

Beberapa masalah umum yang terkait dengan Vocabulary, Vue-Vocabulary, dan Font saat ini:

  • Tidak ada dokumentasi; dan meskipun ada, bagian-bagiannya tersebar di seluruh situs netlify. Hal ini tidak memungkinkan pengguna, developer, atau kontributor eksternal menggunakan library kami.

    • Untuk membuka komponen tertentu dan menyalin kode yang sesuai, Anda harus mengklik beberapa kali. Penelusuran Google sederhana untuk sesuatu seperti “Vokabulasi CC komponen Tabs” tidak menampilkan informasi yang diinginkan. Opsi Penelusuran dalam panduan dokumentasi akan sangat meningkatkan UX.

    • Deskripsi yang sedikit lebih mendetail secara tekstual untuk komponen, yang menjelaskan detail yang tidak jelas.

    • Tidak ada opsi live run. Run live didukung oleh berbagai situs seperti JSFiddle, yang memungkinkan developer merasakan komponen tanpa menjalankan seluruh aplikasi untuk melihat cara kerjanya.

Solusi

Ada beberapa solusi yang mungkin. Namun, saya akan membahas beberapa di antaranya di sini, dan menyajikan solusi akhir saya di bagian kesimpulan:-

= Menggunakan readthedocs readthedocs adalah solusi yang terkenal untuk menulis dokumentasi library open source. Alat ini didasarkan pada Sphinx, alat dokumentasi python.

Kelebihan:

  1. Bentuk pembuatan dokumentasi yang diterima secara luas dan digunakan oleh organisasi seperti Ethereum (Solidity).
  2. Dokumentasi terstruktur secara optimal.
  3. Hosting statis gratis.

Kekurangan:

  1. Kurangnya kontrol absolut atas gaya visual.

= Menggunakan Sphinx Kita juga dapat menggunakan sphinx secara native untuk bagian dokumentasi, yang menyediakan fitur yang baik untuk semua tujuan kita.

Kelebihan:

  1. Alat python yang paling populer untuk dokumentasi.
  2. Memiliki dukungan untuk penelusuran dokumentasi juga.
  3. CSS default dapat diganti dengan CSS kustom; beberapa kontrol atas HTML menggunakan file .rst.

Kekurangan:

  1. Akan melibatkan coding dalam format python dan teks yang disusun ulang (.rst) yang akan berbeda dari bahasa project yang disarankan.

= Menggunakan Tema Jekyll Tema Jekyll terintegrasi dalam halaman github, dan ada template yang sudah ada sebelumnya yang dapat disesuaikan sesuai kebutuhan kita.

Kelebihan:

  1. Tema dokumentasi siap pakai untuk semua tujuan.
  2. CSS dan gaya default dapat diganti dengan gaya kustom, serta kontrol atas HTML.
  3. Menarik CSS Primer default untuk mem-build halaman.
  4. Integrasi mudah dengan halaman GitHub.

Kekurangan:

  1. Mungkin tidak memberikan struktur dokumentasi terbaik.

=Menggunakan halaman GitHub Halaman GitHub standar untuk mem-build situs statis (HTML, CSS, JS).

Kelebihan:

  1. Kontrol penuh atas hampir semua hal yang dipermasalahkan.
  2. Fleksibilitas maksimum dalam menentukan tata letak, warna, dan gaya.
  3. Penggunaan komponen Vocabulary yang mudah.
  4. Penyematan cuplikan kode yang mudah, dan link run live.

Kekurangan:

  1. Mungkin merupakan pendekatan yang lebih memakan waktu.

= Menggunakan Haroopad Solusi markdown alternatif akan diberikan.

Kelebihan:

  1. Akan melibatkan coding yang rumit minimal.
  2. Fokusnya adalah pada penulisan dokumentasi dengan sempurna.

Kekurangan:

  1. Kurangnya kontrol atas CSS.
  2. Mungkin memiliki atau tidak memiliki dukungan komunitas terbaik.
  3. Mungkin tidak mendukung MDX.

= Menggunakan MKDocs Tindakan ini akan memberikan solusi markdown alternatif lainnya.

Kelebihan:

  1. Akan melibatkan coding yang rumit minimal (lagi).
  2. Menulis lebih banyak, pendekatan Kode Lebih Sedikit.

Kekurangan:

  1. Kurangnya kontrol atas CSS.
  2. Mungkin tidak memiliki dukungan komunitas terbaik.
  3. Menggunakan python; mungkin akan muncul lebih lanjut kebutuhan untuk menjalankan instance Amazon S3.

= Menggunakan VueJS +StorybookJS Pendekatan ini biasanya digunakan di seluruh Vocabulary dan repositori turunannya.

Kelebihan:

  1. Memilih teknologi yang dijamin akan berfungsi dengan baik, berdasarkan pengalaman kerja sebelumnya.
  2. Pemahaman tentang codebase.
  3. Tidak ada teknologi yang kompeten di bidang ini.

Kekurangan:

  1. Opsi yang lebih sederhana mungkin juga tersedia untuk tujuan yang sama.

Sebagai kesimpulan, saya ingin berpikir bahwa pendekatan yang melibatkan pendekatan VueJS+Storybook (HTML,CSS,JS) tampaknya paling sesuai, mengingat saya juga merasa nyaman dengan pendekatan tersebut. Namun, hal ini juga berarti bahwa kita tidak akan sepenuhnya keluar dari jalur dalam mengembangkan aplikasi ini. Penggunaan komponen CC-Vocabulary juga cukup mudah. Namun, untuk menentukan struktur dokumentasi, kita harus mempertimbangkan cara konten dibagi di antara subjudul dalam dokumentasi readthedocs. Saya terkesan dengan situs Semantic-UI (yang menggunakan StoryBook) karena memiliki tampilan minimalis dan seseorang dapat dengan mudah mengetahui apa yang mereka inginkan hanya dengan beberapa klik. Selain Semantic-UI, saya juga melihat Desain Material, Primer, Bootstrap, Desain Carbon, dll. untuk digunakan sebagai panduan gaya visual UI dan sistem desain untuk pekerjaan saya. Kita juga dapat mencari tema dokumentasi Jekyll siap pakai untuk mendapatkan inspirasi.