Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- Linux Foundation
- Penulis teknis:
- boron
- Nama proyek:
- Mengerjakan ulang hosting & pembuatan dokumentasi serta Menyusun ulang halaman memulai dan panduan developer.
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Abstrak :
Dokumentasi dirancang untuk membantu pengguna akhir dan pengembang untuk menggunakan suatu produk atau layanan. Dokumentasi yang baik sangat penting karena menyediakan cara bagi pengguna untuk mempelajari cara menggunakan software, fitur, tips, trik, dan juga menyelesaikan masalah umum yang dihadapi saat menggunakan software tersebut. Ini juga mengurangi biaya dukungan dan merupakan bagian dari identitas produk dan {i>open source<i}: dokumentasi yang baik adalah tanda sehatnya produk dan tim pengembang.
Tanpa dokumentasi yang baik, pengguna mungkin tidak tahu bagaimana melakukan hal-hal di atas secara efektif dan efisien. Dokumentasi dapat memainkan peran penting dalam memastikan kesuksesan suatu produk karena komunikasi yang hebat adalah dan akan selalu menjadi jantung bisnis atau produk apa pun dan dokumentasi yang hebat hanya mengambil komunikasi itu dan menempatkannya dalam kerangka kerja yang mudah dikelola yang dapat diakses semua orang untuk sukses.
Setiap situs dokumentasi memerlukan pipeline alur kerja pembangunan dan hosting yang baik, dalam organisasi seperti AGL, dengan banyak versi dan banyak dokumentasi elaboratif, file dokumentasi (markdown) tersebar di beberapa repositori, sehingga tugas pemeliharaan dan pembaruannya menjadi sangat kompleks dan memakan waktu.
Status Saat Ini :
- Situs dokumen AGL didasarkan pada sekumpulan file markdown yang diambil dari berbagai repositori.
- Halaman dokumen saat ini dihosting dalam masing-masing sumber sebagai markdown menggunakan mesin project corova.
- Ini mengarah ke empat pengaturan repositori untuk proses build 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 dari file Markdown secara otomatis.
- Sumber Docs [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] : Men-deploy repositori halaman GitHub 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 fetch_files.yml yang terletak di docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Alur kerja pembuatan situs dokumentasi agl saat ini : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- section_version.yml berisi link ke semua file yaml buku yang akan melanjutkan proses 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, proses alat untuk menghasilkan situs dokumen AGL di docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] di-deploy.
- Proses pemeliharaan pipeline saat ini tidak mudah dilakukan oleh pengguna dan developer, terutama bagi kontributor baru. Pipeline alur kerja (membangun dan hosting) ini dapat lebih sederhana dan efisien bagi developer untuk berfokus pada bagian dokumentasi daripada mempertahankan pembuatan dokumentasi dan alur kerja deployment.