Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan proyek
- Organisasi open source:
- The Linux Foundation
- Penulis teknis:
- boron
- Nama project:
- Mengerjakan ulang hosting & pembuatan dokumentasi serta Menyusun ulang halaman memulai dan panduan developer.
- Durasi project:
- Durasi standar (3 bulan)
Project description
Abstrak :
Dokumentasi dirancang untuk membantu pengguna akhir dan developer menggunakan produk atau layanan. Dokumentasi yang baik sangat penting karena memberikan cara bagi pengguna untuk mempelajari cara menggunakan software, fitur, tips, trik, dan juga menyelesaikan masalah umum yang dihadapi saat menggunakan software. Dokumentasi ini juga mengurangi biaya dukungan dan merupakan bagian dari identitas produk perusahaan dan open source : dokumentasi yang baik adalah tanda kesehatan produk dan tim developer.
Tanpa dokumentasi yang baik, pengguna mungkin tidak tahu cara melakukan hal-hal di atas secara efektif dan efisien. Dokumentasi dapat memainkan peran penting dalam memastikan kesuksesan produk karena komunikasi yang baik selalu menjadi inti dari bisnis atau produk apa pun. Dokumentasi yang baik akan mengambil komunikasi tersebut dan menempatkannya dalam kerangka kerja yang mudah dikelola yang dapat diakses oleh semua orang untuk mencapai kesuksesan.
Setiap situs dokumentasi memerlukan pipeline alur kerja pembuatan dan hosting yang baik. Di organisasi seperti AGL, dengan beberapa versi dan banyak dokumentasi yang elaboratif, file dokumentasi (markdown) tersebar di beberapa repositori, sehingga tugas memelihara dan memperbaruinya menjadi sangat rumit dan memakan waktu.
Status Saat Ini :
- Situs dokumen AGL didasarkan pada kumpulan file markdown yang diambil dari berbagai repositori.
- Halaman dokumen saat ini dihosting dalam masing-masing sumber sebagai markdown menggunakan mesin project cordova.
- Hal ini akan menghasilkan penyiapan empat repositori untuk proses pembuatan dan hosting dokumentasi :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Berisi template situs Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : Berisi alat untuk membuat situs teknis secara otomatis dari file Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Sumber (markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) untuk dokumen umum, panduan.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Repositori halaman GitHub yang di-deploy untuk situs dokumentasi [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Alat (skrip) yang tersedia di docs-tools [https://github.com/automotive-grade-linux/docs-tools] menangani pengumpulan dan pembuatan template semua file markdown sesuai dengan fetched_files.yml yang ada di docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Alur kerja saat ini untuk pembuatan situs dokumentasi AGL : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- section_version.yml berisi link ke semua file YAML buku, yang kemudian mengambil semua file YAML buku dari repositori jarak jauh ke docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. File YAML buku berisi semua URL ke file markdown Anda dari repositori jarak jauh.
- Segera setelah semua file markdown diambil, alat akan diproses untuk membuat situs dokumen AGL di docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] yang kemudian di-deploy.
- Proses saat ini untuk memelihara pipeline tidak ramah bagi pengguna dan developer, terutama bagi kontributor baru. Pipeline alur kerja ini (pembuatan dan hosting) dapat disederhanakan dan dioptimalkan agar developer dapat lebih berfokus pada bagian dokumentasi, bukan mempertahankan alur kerja pembuatan dan deployment dokumentasi.