Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- Linux Foundation
- Penulis teknis:
- boron
- Nama proyek:
- Mengerjakan ulang hosting &pembuatan dokumentasi serta Merestrukturisasi 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 sarana bagi pengguna untuk mempelajari cara menggunakan software, fitur, tips, trik, dan juga menyelesaikan masalah umum yang dialami saat menggunakan software. Hal ini juga mengurangi biaya dukungan dan merupakan bagian dari identitas perusahaan dan open source produk : 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 adalah dan akan selalu menjadi inti dari bisnis atau produk apa pun dan dokumentasi yang bagus hanya mengambil komunikasi itu dan memasukkannya ke dalam kerangka kerja yang dapat dikelola sehingga semua orang dapat mencapai kesuksesan.
Setiap situs dokumentasi memerlukan pipeline alur kerja pembangunan dan hosting yang bagus, dalam organisasi seperti AGL, dengan beberapa versi dan banyak dokumentasi yang elaboratif, file dokumentasi (markdown) tersebar di beberapa repositori, sehingga tugas mengelola dan memperbaruinya menjadi sangat kompleks dan memakan banyak waktu.
Status Saat Ini :
- Situs dokumen AGL didasarkan pada kumpulan file markdown yang diambil dari berbagai repositori.
- Halaman dokumen saat ini dihosting dalam setiap sumber sebagai markdown menggunakan mesin project cordova.
- Hal ini menghasilkan empat penyiapan 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 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] : 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 fetched_files.yml yang terletak 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 akan 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 memproses untuk membuat situs dokumen AGL di docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] yang di-deploy secara sesuai.
- Proses pemeliharaan pipeline saat ini tidak mudah digunakan oleh pengguna dan developer, terutama bagi kontributor baru. Pipeline alur kerja ini (pembuatan dan hosting) dapat disederhanakan dan disederhanakan lebih lanjut agar developer dapat berfokus pada bagian dokumentasi, bukan mempertahankan alur kerja pembuatan dan deployment dokumentasi.