Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- CERN-HSF
- Penulis teknis:
- SabitaR
- Nama proyek:
- Restrukturisasi & Penyederhanaan Dokumentasi Allpix Squared
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
RINGKASAN Saya memilih proyek Allpix Squared dari CERN-HSF karena dua alasan utama:
Pengembangan keterampilan: Dokumentasi project yang ada saat ini komprehensif dan mengintegrasikan berbagai format konten. Mengaudit dan merestrukturisasi rangkaian dokumen yang lengkap ini akan membantu saya memoles keterampilan menulis dan arsitektur info saya. Selain itu, domain project (fisika partikel) baru bagi saya. Saya diminta untuk mengasah keterampilan interaksi developer. Saya percaya bahwa penulis teknis dapat memproses input dari developer dan menyajikan konten yang berguna untuk semua tingkat pengguna, JIKA kami melakukan riset latar belakang yang diperlukan, dan mengajukan pertanyaan yang tepat. Proyek ini memungkinkan aku menguji teori ini!
Pengetahuan teknis: Project ini membutuhkan Hugo - alat yang ditampilkan di bagian atas daftar tugas saya. Saya tidak sabar untuk mempelajari alur kerja LaTeX-Markdown-Hugo-GitLab-CI.
Selama fase eksplorasi penulis teknis, saya berinteraksi secara singkat dengan mentor proyek dan membiasakan diri dengan struktur paket dokumen yang ada. Saya juga membuat situs demo (https://ap2-demo.netlify.app/) untuk menguji apakah saya dapat mengonfigurasi Hugo dan Docsy dengan benar di komputer Windows. Saya dapat men-deploy situs ke Netlify, tetapi tidak ke Gitlab Pages. Agar project ini dapat mempertahankan alur kerja deployment-nya saat ini, saya akan menemukan cara untuk men-deploy tema Hugo Docsy ke Gitlab Pages.
HASIL PROYEK YANG DIHARGAI - Situs web proyek yang disederhanakan yang mengintegrasikan dokumentasi, referensi kode, tutorial, dan berita. - Panduan pengguna yang disusun ulang dan ditinjau yang memisahkan konten yang ditujukan untuk pengguna dan developer, serta menyertakan informasi yang sebelumnya tidak ada. - Alur kerja tutorial dari contoh dokumentasi yang tersedia, FAQ, dan masalah yang sering dihadapi.
ALAT PROYEK Dokumentasi Allpix Squared saat ini menggunakan LaTeX, Doxygen, pandoc, dan Hugo, selain GitLab dan Gitlab CI. Saya dan mentor proyek telah mengobrol tentang kemungkinan memindahkan konten dari LaTeX ke Markdown dengan plugin MathJax. Jika saya berhasil, alur kerja dokumen akan melibatkan Hugo, Markdown, Doxygen, git, dan Gitlab CI. Untuk menyimpan tutorial dalam {i>website<i}/platform yang sama, saya akan menggunakan Hugo dan Markdown. Saya ingin tahu tentang kelayakan penggunaan Codelabs-as-a-Tool (ClaaT) untuk tutorial. Pada bulan Juli ini, saya berharap dapat menguji alur kerja ClaaT-Hugo dan mendiskusikannya dengan para mentor, jika terpilih.
DURASI PROYEK Saya meminta untuk menyelesaikan project Allpix Squared dalam periode standar tiga bulan (14 September 2020 - 30 November 2020). Selama periode tersebut, saya akan menghabiskan sekitar 15 jam per minggu untuk project tersebut. Jam kerja ini akan mencakup pertemuan mentor dan email terkait, sesuai kebutuhan. Saya akan mematuhi jadwal GSoD untuk ikatan komunitas dan finalisasi proyek juga.
TUGAS PROJECT Berikut ini cara saya mengimplementasikan pembaruan yang diusulkan ke paket dokumen Allpix Squared yang ada: 1. Melakukan riset, diskusi, dan pelajari opsi (17 Agustus - 13 Sep 2020): - Memahami persyaratan project - Instal software Allpix Squared untuk mengidentifikasi info yang tidak lengkap, jika ada, dalam dokumen saat ini. - Minta kredensial yang diperlukan. - Buat alur kerja pengguna untuk berbagai pengguna Allpix Squared - Klasifikasikan konten berdasarkan peran pengguna - Periksa implikasi konversi file LaTeX ke Markdown - Konsolidasi repositori sumber atau pahami cara bekerja dengan beberapa repositori git - Bonus: Uji CLaaT sebagai opsi untuk tutorial - Bonus: Buat panduan gaya cepat/referensi kode singkat untuk membantu kontributor mengelola dokumentasi Linimasa:
Mengubah struktur, meninjau, dan meningkatkan kualitas konten (14 Sep - 19 Okt 2020): Dua tugas per minggu, sekitar 5-7 jam per tugas. Linimasa ini mencakup minggu jeda untuk menangani keterlambatan atau masalah yang tidak terduga.
- Tinjau konten dan klasifikasi pengguna yang ada dengan mempertimbangkan alur kerja pengguna
- Membuat garis besar dan menguji alur kerja konten yang disusun ulang untuk pengguna yang berbeda
- Mendapatkan dan menyempurnakan konten yang tidak ada
- Mengonversi {i>file<i} LaTeX menjadi Markdown
- Menyelesaikan panduan pengguna dan daftar isi panduan developer
- Membuat PDF panduan pengguna dan developer
- Bonus: Membuat struktur konten untuk tutorial dari contoh dan isu
- Bonus: Menyiapkan alur kerja tutorial untuk contoh petunjuk Linimasa: 5 minggu (fase pengembangan Dokumen)
Membuat situs (19 Okt - 30 Nov 2020): 1-2 tugas per minggu, sekitar 5-7 jam per tugas. Linimasa ini mencakup minggu buffering untuk memecahkan masalah dan menyesuaikan hasil akhir.
- Memahami dan menguji alur kerja publikasi
- Buat struktur {i>website<i} menggunakan Hugo dan Docsy
- Uji cara mempertahankan deployment otomatis dan alur kerja saat ini menggunakan Docsy
- Ambil konten dari Doxygen
- Mengembangkan panduan pengguna, panduan developer, dan tutorial dari konten LaTex atau Markdown
- Menyelesaikan tampilan dan nuansa situs project (logo, warna, template, tata letak, link, kegunaan, dan Gitlab CI/CD) Linimasa: 6 minggu (fase pengembangan Dokumen)