Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- ScummVM
- Penulis teknis:
- Cadi
- Nama project:
- Meluncurkan Portal Dokumentasi
- Durasi project:
- Durasi standar (3 bulan)
Project description
Tujuan:
- Untuk menghasilkan dokumentasi pengguna akhir yang berkualitas tinggi dan memiliki versi dengan menggabungkan informasi dalam jumlah besar dari berbagai sumber dan menulis ulang informasi untuk kejelasan, konsistensi, dan kelengkapan.
- Dokumentasi harus mudah dipahami oleh pemula, tanpa merendahkan pengguna yang paham teknologi.
- Untuk membuat portal dokumentasi menggunakan generator situs statis.
- Untuk membuat dokumentasi pengguna akhir yang siap menghadapi masa depan dengan membuat template dan petunjuk cara yang mendetail untuk kontributor open source di masa mendatang.
Situasi saat ini:
- Dokumentasi ScummVM yang tersedia tersebar di beberapa sumber.
- Informasi sulit ditemukan dan sering diduplikasi; Anda mudah tersesat di halaman yang tidak jelas.
- Sulit untuk mengetahui informasi mana yang terbaru dan mana yang sudah tidak berlaku.
- Beberapa informasi tidak ada atau tidak lengkap.
Memperbaiki masalah:
Struktur dokumentasi yang disarankan:
Halaman Landing
|-- Memulai
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (platform)
|-- Menggunakan ScummVM
| |-- Peluncur
| |-- Setelan global
| |-- Setelan game
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
|-- Musik dan suara
|-- Bantuan
| |-- FAQ
| |-- Kontak
| |-- Masalah umum
| -- Reporting a bug
|-- Game Notes-- Catatan Rilis
- Memulai:
Pengguna baru sering kali mencari panduan memulai cepat untuk memulai secepat mungkin. Meskipun penginstalan {i>ScummVM<i} bisa menjadi rumit pada beberapa platform, menginstalnya ke komputer tidaklah rumit.
Panduan memulai harus mencakup hal-hal berikut:
- Cara menginstal ScummVM di Windows, Mac, dan Linux.
Cara memuat, menambahkan, dan meluncurkan game.
Menginstal ScummVM:
Jika penginstalan tidak intuitif, atau jika pengguna mungkin tidak memiliki dasar teknis yang kuat, pengguna memerlukan panduan komprehensif untuk menginstal ScummVM di platform apa pun yang didukung.
Setiap halaman penginstalan yang komprehensif harus mencakup hal berikut:
- Persyaratan/prasyarat sistem apa pun.
- Cara mendownload versi ScummVM yang sesuai.
- Cara menginstal ScummVM.
- Cara memuat game ke platform yang dipilih, terutama jika itu bukan platform yang didesain untuk game tersebut.
Cara meluncurkan ScummVM, menambahkan game, dan meluncurkan game.
Menggunakan ScummVM:
Pengguna memerlukan dokumen referensi yang menjelaskan cara menggunakan ScummVM.
Dokumen referensi harus mencakup hal-hal berikut:
- Antarmuka Peluncur; tampilan setiap jendela dan tab serta cara kerjanya.
- Penjelasan tentang setelan yang tersedia, baik global maupun khusus game.
Pintasan keyboard/tombol pintas.
Opsi lanjutan:
Pengguna tingkat lanjut memerlukan informasi tambahan yang lebih teknis tentang opsi yang tersedia untuk mereka guna menyesuaikan cara game berjalan.
- Catatan game:
Informasi khusus game yang perlu diketahui pengguna; termasuk, tetapi tidak terbatas pada: - Keunikan penginstalan - File tambahan yang diperlukan - Kontrol yang tidak biasa atau berbeda
- Masalah umum:
Bagian ini harus berisi semua bug umum yang spesifik untuk rilis tersebut.
- Catatan rilis:
Meskipun dokumentasi kami akan diberi versi, memiliki bagian Catatan Rilis dapat membantu memberikan ringkasan perubahan dalam rilis terbaru. Hal ini dapat mencakup beberapa area yang saat ini berada di luar cakupan dokumentasi ini, seperti game yang baru didukung atau informasi tentang mesin baru.
Rencana serangan:
Saya mengusulkan untuk memulai dengan membuat template untuk halaman Menginstal ScummVM, karena itu akan menjadi cara termudah bagi saya untuk mendapatkan informasi yang saya perlukan dari pengelola/developer port (terutama jika informasi ini sedikit atau tidak ada). Saya akan mengisi otomatis informasi apa pun yang sudah saya miliki dari dokumentasi yang ada, yang kemudian dapat diperiksa kelengkapan, akurasi, dan mata uangnya, atau ditambahkan sesuai kebutuhan.
Selanjutnya, saya akan menelusuri dokumentasi yang ada; README, wiki, dan situs. Seiring berjalannya waktu, saya akan menulis ulang dan menambahkan ke setiap bagian sesuai kebutuhan dan mengambil semua informasi ke portal baru. Saya juga akan mencatat informasi apa yang diambil dari mana, untuk memastikan bahwa setelah portal ditayangkan, tidak ada duplikat, kontradiksi, atau anomali lainnya.
Selama proses ini, saya akan berkoordinasi dengan mentor, developer, pengelola port, dan pakar materi pokok lainnya untuk mendapatkan informasi yang belum ada, serta memastikan setiap halaman seaktual dan selengkap mungkin.
Dalam semangat kolaborasi dan tunduk pada persetujuan dari mentor, saya ingin portal yang sedang dikerjakan dapat diakses oleh komunitas ScummVM selama proses penulisan, untuk menerima masukan secara real time dan memastikan tidak ada yang terlewat.
Sebaiknya gunakan panduan gaya, seperti panduan gaya dokumentasi developer Google, untuk memastikan konsistensi untuk kumpulan pekerjaan ini dan untuk semua dokumentasi ke depannya.
Jika memungkinkan, saya akan menggunakan screenshot, gif, dan alat bantu visual lainnya untuk meningkatkan pemahaman.
Linimasa yang diusulkan:
Ikatan komunitas 17 Agustus - 13 September 2020
Teruslah meluangkan waktu untuk berbicara dengan mentor dan komunitas ScummVM yang lebih luas untuk menyesuaikan visi project dan menyelesaikan detail seperti struktur dan konten dokumen.
Minggu ke-1 14 September - 20 September
- Buat template untuk halaman penginstalan khusus platform.
- Isi otomatis template dengan informasi yang ada dan distribusikan ke pengelola/developer port yang sesuai untuk mendapatkan informasi lebih lanjut.
Minggu ke-2 21 September - 27 September
- Siapkan portal dokumentasi baru.
Minggu ke-3 28 September - 4 Oktober
Menggunakan ScummVM: - Antarmuka - Setelan global Menginstal ScummVM: - Panduan penginstalan khusus platform saat template yang telah selesai ditampilkan kepada saya.
Minggu ke-4 5 Oktober - 11 Oktober
Menggunakan ScummVM: - Setelan game - Pintasan keyboard Menginstal ScummVM: - Panduan penginstalan khusus platform saat template yang telah selesai ditampilkan kepada saya
Minggu ke-5 12 Oktober - 18 Oktober
Opsi lanjutan: - Cloud dan LAN - Pemetaan Kontrol Menginstal ScummVM: - Panduan penginstalan khusus platform saat template yang telah selesai ditampilkan kepada saya
Minggu ke-6 19 Oktober - 25 Oktober
Opsi lanjutan: - Konfigurasi - Opsi command line Menginstal ScummVM: - Panduan penginstalan khusus platform saat template yang telah selesai ditampilkan kepada saya
Minggu 7 26 Oktober - 1 November
Opsi lanjutan: - Grafis - Audio Menginstal ScummVM: - Panduan penginstalan khusus platform saat template yang telah selesai ditampilkan kepada saya
Minggu 8 2 November - 8 November
Bantuan: - FAQ - Kontak - Masalah umum
Menginstal ScummVM: - Panduan penginstalan khusus platform saat template yang telah selesai ditampilkan kepada saya
Minggu ke-9 9 November - 15 November
Bantuan: - Melaporkan bug - Catatan game - Catatan rilis
Menginstal ScummVM: - Menyelesaikan panduan platform yang belum selesai.
Minggu ke-10 16 November - 22 November
- Pengeditan akhir, pemeriksaan tata bahasa, dan penyelesaian keputusan terkait portal seperti navigasi sidebar, penyesuaian tema/CSS, dll.
- Pastikan semua link berfungsi seperti yang diharapkan.
- Pastikan gambar/gif ditampilkan dengan benar.
Minggu ke-11 23 November - 30 November
- Selesaikan item yang tertunda dan luncurkan portal secara resmi.
- Setelah portal diluncurkan, hapus informasi yang tidak diperlukan dari sumber lain melalui konsultasi dengan mentor.