Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- CERN-HSF
- {i>Technical writer <i}(Penulis teknis):
- SabitaR
- Nama project:
- Restrukturisasi &Penyederhanaan Dokumentasi Allpix Squared
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
RINGKASAN Saya telah memilih project Allpix Squared CERN-HSF karena dua alasan utama:
Membangun keterampilan: Dokumentasi project yang ada bersifat komprehensif dan mengintegrasikan berbagai format konten. Mengaudit dan menyusun ulang rangkaian dokumen yang luas ini akan membantu saya meningkatkan keterampilan menulis dan arsitektur info saya. Selain itu, domain project (fisika partikel!) adalah hal baru bagi saya. Hal ini mendorong saya untuk mengasah keterampilan interaksi developer saya. Saya percaya bahwa penulis teknis dapat memproses input dari developer dan menyajikan konten yang berguna untuk semua tingkat pengguna, JIKA kita melakukan riset latar belakang yang diperlukan, dan mengajukan pertanyaan yang tepat. Dengan project ini, aku bisa menguji teori ini.
Pengetahuan teknis: Project ini memerlukan Hugo - alat yang berada di bagian atas daftar yang harus saya pelajari. Saya ingin mempelajari alur kerja LaTeX-Markdown-Hugo-GitLab-CI.
Selama fase eksplorasi penulis teknis, saya berinteraksi dengan mentor project secara singkat dan memahami struktur suite 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 saat ini, saya akan menemukan cara untuk men-deploy tema Hugo Docsy ke Gitlab Pages.
HASIL PROJEK YANG DIHARAPKAN - Situs project yang disederhanakan yang mengintegrasikan dokumentasi, referensi kode, tutorial, dan berita. - Manual 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 cara kerja, FAQ, dan masalah umum yang tersedia.
ALAT PROJECT Selain GitLab dan Gitlab CI, dokumentasi Allpix Squared saat ini menggunakan LaTeX, Doxygen, pandoc, dan Hugo. Saya dan mentor project telah berdiskusi tentang kemungkinan pemindahan konten dari LaTeX ke Markdown dengan plugin MathJax. Jika 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 kelayakan penggunaan Codelab-as-a-Tool (ClaaT) untuk tutorial. Pada bulan Juli ini, saya berharap dapat menguji alur kerja ClaaT-Hugo dan mendiskusikannya dengan mentor, jika terpilih.
DURASI PROJEK Saya meminta untuk menyelesaikan project Allpix Squared dalam jangka waktu tiga bulan standar (14 September 2020 - 30 November 2020), selama itu saya akan menghabiskan waktu sekitar 15 jam per minggu. Jam ini akan mencakup pertemuan mentor dan email terkait, sesuai kebutuhan. Saya juga akan mematuhi linimasa GSoD untuk ikatan komunitas dan penyelesaian project.
TUGAS PROJEK Berikut cara saya menerapkan pembaruan yang diusulkan ke suite dokumen Allpix Squared yang ada: 1. Meneliti, mendiskusikan, dan mempelajari opsi (17 Agustus - 13 September 2020): - Memahami persyaratan project - Menginstal software Allpix Squared untuk mengidentifikasi info yang tidak ada, jika ada, dalam dokumen saat ini. - Meminta kredensial yang diperlukan. - Membuat alur kerja pengguna untuk berbagai pengguna Allpix Squared - Mengklasifikasikan konten menurut peran pengguna - Memeriksa implikasi mengonversi file LaTeX ke Markdown - Menggabungkan repositori sumber atau memahami cara menggunakan beberapa repositori git - Bonus: Menguji CLaaT sebagai opsi untuk tutorial - Bonus: Menulis panduan gaya cepat/referensi shortcode untuk membantu kontributor mengelola dokumen Linimasa: Fase ikatan komunitas
Merstrukturisasi, meninjau, dan meningkatkan kualitas konten (14 Sep - 19 Okt 2020): Dua tugas per minggu, sekitar 5-7 jam per tugas. Linimasa ini mencakup periode buffer untuk menangani penundaan atau masalah yang tidak terduga.
- Meninjau konten dan klasifikasi pengguna yang ada dengan mempertimbangkan alur kerja pengguna
- Menguraikan dan menguji alur kerja konten yang disusun ulang untuk berbagai pengguna
- Menemukan dan meningkatkan kualitas konten yang tidak ada
- Mengonversi file LaTeX ke Markdown
- Menyelesaikan panduan pengguna dan daftar isi panduan developer
- Membuat PDF panduan pengguna dan developer
- Bonus: Membuat struktur konten untuk tutorial dari contoh dan masalah
- Bonus: Menyiapkan alur kerja tutorial untuk contoh petunjuk Rentang waktu: 5 minggu (Tahap pengembangan Dokumen)
Membuat situs (19 Oktober - 30 November 2020): 1-2 tugas per minggu, sekitar 5-7 jam per tugas. Linimasa ini mencakup minggu buffer untuk memecahkan masalah dan menyesuaikan output akhir.
- Memahami dan menguji alur kerja publikasi
- Membuat struktur situs menggunakan Hugo dan Docsy
- Menguji cara mempertahankan deployment otomatis dan alur kerja saat ini menggunakan Docsy
- Mengambil konten dari Doxygen
- Mengembangkan manual 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)