Project Kolibri

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

Ringkasan project

Organisasi open source:

Kolibri

Penulis teknis:

StephDix

Nama project:

Konvensi Gaya dan Alur Kerja Dokumentasi Ekosistem Kolibri

Durasi project:

Berjalan lama (5 bulan)

Project description

Abstrak

Dokumen ini menjelaskan penerapan pedoman Gaya dan pengelolaan alur kerja ke informasi terdokumentasi Learning Equality untuk project Ekosistem Kolibri.

Ringkasan

Proposal saya terdiri dari empat fase. Pada tahap pertama, saya akan menyelesaikan LE Documentation Style Guide dengan panduan aksesibilitas, penulisan, dan rekomendasi format dengan mengikuti konsep dan panduan gaya dalam pengembangan software. Pada tahap kedua, saya akan melakukan Audit Kualitas terhadap dokumen ReadTheDocs dan GoogleDocs. Rencana Audit mengintegrasikan penggunaan checklist untuk mengevaluasi kepatuhan terhadap Panduan gaya. Checklist ini akan membantu mencatat temuan dan menerapkan perubahan pada dokumentasi. Pada fase ketiga, saya akan mengerjakan struktur, tampilan, dan nuansa template dari dokumen ReadTheDocs dan Google Dokumen. Saya akan membuat repositori template dan gambar di Google Drive yang mengidentifikasi setiap kategori template jenis dokumen utama untuk digunakan kembali dalam penerapan mendatang. Saya akan melengkapi tugas ini dengan membuat template untuk mengirimkan masalah dokumen guna memudahkan identifikasi dalam peninjauan permintaan pull. Terakhir, saya akan membuat Panduan Kontributor yang mengelompokkan berbagai referensi berguna bagi setiap grup kolaborator untuk meningkatkan pengalaman mereka dalam mengakses informasi.

Tujuan dan ruang lingkup

Tujuan di balik rencana penerapan ini adalah untuk meningkatkan pengalaman pengguna akhir yang menggunakan dokumen Kolibri dan membantu anggota tim serta kontributor untuk menghasilkan dokumentasi yang lebih baik dan kolaborasi aktif di komunitas. Penerapan ini berlaku untuk ReadTheDocs dan subkumpulan dokumen Google Dokumen di Ekosistem Kolibri.

Audiens

Audiens utama pengimplementasi, administrator, dan pengguna akhir menjadi konsumen paling kritis dari dokumentasi Kolibri. Audiens sekunder dari anggota tim dan kolaborator untuk produksi dan penggunaan dokumentasi Kolibri mereka.

Tujuan

Panduan Gaya dan sistem alur kerja untuk Dokumentasi Ekosistem Kolibri mengharapkan pengguna untuk: Membuat dokumentasi yang mudah dipahami dengan bahasa yang mudah diakses dan tata letak yang konsisten. Mempertahankan pemeliharaan praktik kualitas setelah dokumentasi. Mempertahankan kemudahan akses ke informasi di antara saluran dokumentasi. Memperkuat inisiatif kolaboratif di komunitas open source Kolibri.

Sumber informasi

Sumber informasi saya adalah Kolibri, Kolibri Studio, dokumen RTD Kolibri Development, dan Toolkit Kolibri dari Google Drive.
Radina Matic yang luar biasa sangat membantu dalam menyediakan aktivitas pemanasan dan aktivitas khusus project. Masukannya tentang hal yang dikonsepkan organisasi sebagai ""Pedoman" dan ""Pedoman"" serta tentang keberadaan Panduan untuk kontributor membantu saya mengatur ide-ide dan menyusun kesimpulan.

Software

Saya akan mengembangkan draf Panduan Gaya di Google Dokumen. Platform dokumen ini sangat cocok untuk melakukan iterasi saat siap dipublikasikan. Untuk Audit QA, saya akan menggunakan Google Formulir untuk melakukan dan mengevaluasi dokumen. Spreadsheet akan menyimpan respons formulir untuk kontrol dokumen. Saya akan memfaktorkan ulang dokumen RTD menggunakan GitHub. Saya telah menggunakan Git, Gitkraken, GitHub, dan Gitlab. Saya memiliki pengetahuan praktis tentang Markdown dan beberapa RestructuredText. Saya berencana untuk membantu memperbaiki dokumentasi agar dapat terus mempelajari sintaksis. Saya akan menggunakan Sharex untuk gambar dan gif. Saya menyukai alat ini karena merender dalam berbagai format output. Saya akan menggunakan Diagram untuk membuat diagram dan edisi gambar. Software diagram terintegrasi dengan baik dengan GoogleDokumen, Google Drive, dan LibreOffice. Kondisi dokumentasi Pada tahap eksplorasi, saya merevisi sebagian besar dokumentasi Kolibri. Saya menemukan kesalahan tata bahasa, kesalahan ketik, inkonsistensi dalam tata letak, tipografi, penggunaan gambar, dan juga, jalur dokumentasi yang membingungkan dari sebagian besar dokumentasi project. Misalnya, dalam Panduan Pengguna Kolibri, bagian pemecahan masalah adalah subtopik, bukan topik. Informasi ini cukup penting bagi pengguna akhir untuk mengaksesnya dari daftar isi. Sebagai alternatif kedua, mereka dapat menggunakan kotak penelusuran dan hierarki daftar isi untuk memperluas topik lainnya dan menemukan artikel pemecahan masalah.

Untuk mengakses bagian “Troubleshooting”, Anda harus menelusurinya atau memperluas “Manage Kolibri” untuk melihat bahwa Troubleshooting ada sebagai bagian dari dokumentasi. Panduan vs Pedoman Untuk proposal project ini, saya menganalisis dua dokumen: Panduan Gaya Dokumentasi Pengguna Kolibri LE dan Pedoman terjemahan LE. Dalam Panduan Kolibri LE, saya membuat rekomendasi dan komentar dari rencana Dokumentasi dan garis besar topik yang saya usulkan serta beberapa hal lain yang perlu ditingkatkan pada Panduan. Untuk Panduan Terjemahan LE, saya mengubah format dan gaya berdasarkan rekomendasi saya dan konvensi yang ada di Panduan Gaya. Hal yang paling menarik perhatian saya selama analisis adalah kesalahpahaman yang ada antara dokumen yang dikategorikan sebagai Panduan dan Pedoman.

Hasil

Saya melakukan pemeriksaan kualitas pada Panduan Terjemahan LE selain saran dan komentar dengan formulir awal yang saya jelaskan secara lebih mendetail dalam tugas Audit QA. Berikut adalah beberapa komentar akhir yang diperoleh dari evaluasi: Link rusak untuk situs .js Sintaksis ICU Format yang digunakan untuk membuat Panduan ini salah. Dokumen ini adalah Panduan, bukan Pedoman. Tipografi yang tidak konsisten. Penggunaan judul dan judul yang salah, Penggunaan bahasa yang tidak tepat dan penyalahgunaan kontraksi. Penggunaan Teks alternatif yang tidak tepat. Di atas pernyataan/ petunjuk yang berulang.

Temuan untuk kedua dokumen tersebut adalah bagian dari Hasil untuk proposal ini.

Tugas khusus project

• Rekomendasi Panduan Gaya Dokumentasi Pengguna LE (komentar)
• Panduan Terjemahan LE dengan gaya dan format baru.
• Garis Besar Topik
• Linimasa project
• Tugas dokumentasi