Project Kolibri

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

Ringkasan proyek

Organisasi open source:
Kolibri
Penulis teknis:
StephDix
Nama proyek:
Konvensi Gaya Dokumentasi dan Alur Kerja Ekosistem Kolibri
Durasi proyek:
Jangka panjang (5 bulan)

Project description

Abstract

Dokumen ini menjelaskan penerapan pedoman Gaya dan pengelolaan alur kerja pada informasi yang didokumentasikan Learning Equality untuk project Kolibri Ecosystem.

Ringkasan

Proposal saya terdiri dari empat fase. Pada fase pertama, saya akan menyelesaikan LE Documentation Style Guide dengan pedoman aksesibilitas, penulisan, dan rekomendasi format dengan mengikuti konsep LE dan pedoman gaya dalam pengembangan perangkat lunak. Di fase kedua, saya akan melakukan Audit Kualitas atas dokumen ReadTheDocs dan GoogleDocs. Rencana Audit mengintegrasikan penggunaan checklist untuk mengevaluasi kepatuhan terhadap panduan Gaya. {i>Checklist<i} (daftar periksa) ini akan membantu mencatat temuan dan menerapkan perubahan pada dokumentasi. Di tahap ketiga, saya akan mengerjakan struktur, tampilan, dan nuansa template dari dokumen ReadTheDocs dan GoogleDocs. 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 agar mudah diidentifikasi dalam peninjauan permintaan pull. Terakhir, saya akan membuat Panduan Kontributor yang akan mengelompokkan sumber daya yang berguna bagi setiap grup kolaborator untuk meningkatkan pengalaman mereka dalam mengakses informasi.

Tujuan dan ruang lingkup

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

Audiens

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

Tujuan

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

Sumber informasi

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

Software

Saya akan mengembangkan draf Panduan Gaya di Google Dokumen. Platform dokumen ini sangat cocok untuk melakukan iterasi saat dokumen siap dipublikasikan. Untuk Audit QA, saya akan menggunakan Google Formulir untuk melaksanakan dan mengevaluasi dokumen. {i>Spreadsheet<i} akan menyimpan tanggapan formulir untuk kontrol dokumen. Saya akan memfaktorkan ulang dokumen RTD menggunakan GitHub. Saya telah bekerja dengan Git, Gitkraken, GitHub, dan Gitlab. Saya memiliki pengetahuan tentang Markdown dan beberapa RestructuredText. Saya berencana berkontribusi pada perbaikan dokumentasi untuk terus mempelajari sintaksis. Saya akan menggunakan Sharex untuk gambar dan gif. Saya menyukai alat ini karena merender dalam format {i>output<i} yang berbeda. Saya akan menggunakan Diagram untuk membuat diagram dan edisi gambar. Software diagram terintegrasi dengan baik dengan Google Dokumen, Google Drive, dan LibreOffice. Status dokumentasi Dalam fase 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 proyek. Misalnya, dalam Panduan Pengguna Kolibri, bagian pemecahan masalah merupakan subtopik dan bukan topik. Informasi ini tampaknya cukup penting bagi pengguna akhir untuk dapat mengaksesnya dari daftar isi. Sebagai alternatif, mereka dapat menggunakan kotak penelusuran dan hierarki daftar isi untuk meluaskan topik lain dan menemukan artikel pemecahan masalah.

Untuk mengakses bagian "Pemecahan Masalah", Anda harus menelusurinya atau meluaskan "Mengelola Kolibri" untuk menyadari bahwa Pemecahan Masalah ada sebagai bagian dari dokumentasi. Panduan vs Panduan Untuk proposal project ini, saya menganalisis dua dokumen: LE Kolibri User Documentation Style Guide dan LE translation Guidelines. Dalam Panduan LE Kolibri, saya membuat rekomendasi dan komentar dari garis besar topik dan rencana Dokumentasi yang saya usulkan, serta beberapa hal lain yang perlu diperbaiki dalam Panduan ini. Untuk LE Translation Guidelines, saya mengubah format dan gaya berdasarkan rekomendasi dan konvensi yang sudah ada di Style Guide. Hal yang paling menjadi perhatian saya selama analisis adalah kesalahpahaman yang ada di antara dokumen yang dikategorikan sebagai Panduan dan Pedoman.

Hasil

Selain saran dan komentar, saya juga melakukan pemeriksaan kualitas pada LE Translation Guide dengan formulir pendahuluan yang saya jelaskan secara lebih rinci dalam tugas Audit UM (Uji Mutu). Berikut ini beberapa komentar akhir yang diperoleh dari evaluasi: Link rusak untuk situs .js Sintaksis ICU Format yang digunakan untuk membuat Panduan ini salah. Dokumen tersebut adalah Panduan, bukan Pedoman. Tipografi tidak konsisten. Penggunaan {i>heading<i} dan judul yang tidak tepat, Penggunaan bahasa yang tidak tepat, dan penggunaan pemendekan yang tidak tepat. Penggunaan Teks Alternatif yang tidak tepat. Terlalu berulang kali/ petunjuk.

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

Tugas khusus project

  • Rekomendasi Panduan Gaya Dokumentasi Pengguna LE (komentar)
  • LE Translation Guidelines dengan gaya dan format baru.
  • Garis Besar Topik
  • Jangka waktu proyek
  • Tugas dokumentasi