Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan proyek
- Organisasi open source:
- HPX
- Penulis teknis:
- rstobaugh
- Nama proyek:
- Mengedit & Menyederhanakan Dokumentasi HPX yang Ada
- Durasi project:
- Durasi standar (3 bulan)
Project description
Proposal saya adalah mengedit dan menyederhanakan konten dokumentasi HPX yang ada. Proposal saya adalah untuk project jangka waktu standar (tiga bulan) yang berfokus pada merevisi dua bab dari manual grup STE||AR: ""HPX Build System and Launching"" (1) dan ""Configuring HPX Applications"" (2).
Bab tentang ""HPX Build System and Launching"" memiliki beberapa kesalahan tata bahasa dan juga berisi bahasa yang membingungkan serta kapitalisasi istilah yang tidak konsisten seperti “CMake”. Selain itu, bab ini berisi informasi berulang, yang saya rencanakan untuk disusun ulang, digabungkan, dan dipangkas sesuai kebutuhan. Meskipun bab tentang ""Mengkonfigurasi Aplikasi HPX"" juga berisi beberapa kesalahan tata bahasa yang perlu diatasi, perhatian utama saya untuk bab ini adalah kemudahan pengguna. Bab ini memiliki tiga masalah desain utama yang ingin saya atasi:
Beberapa judul tersembunyi dalam teks, sehingga sulit untuk membaca sekilas bab. Saat ini, pengguna harus membaca manual dengan cermat untuk memahami tujuan setiap tabel. Ini bukanlah cara sebagian besar pengguna berinteraksi dengan manual petunjuk, terutama jika mereka sudah membaca konten sebelumnya. Sebagai gantinya, saya berencana untuk memastikan setiap tabel memiliki judul yang jelas dan berbeda, yang dapat dengan mudah dilihat jika pengguna men-scroll teks.
Saat mencantumkan berbagai properti di bawah judul tertentu, properti tidak mengikuti urutan yang logis. Meskipun properti dikelompokkan bersama dalam tema yang sama, tidak ada pengelompokan subgrup, sehingga informasi terasa tersebar. Misalnya, pengguna mungkin menemukan beberapa properti yang berkaitan dengan lokalitas, beberapa properti yang berkaitan dengan subjek lain, lalu properti lain yang berkaitan dengan lokalitas. Kurangnya struktur internal di bawah judul ini mempersulit penentuan lokasi semua informasi tentang subtopik tertentu. Oleh karena itu, saya berencana untuk mengatur ulang beberapa diagram untuk mengelompokkan informasi serupa dengan lebih jelas di bawah setiap judul.
Pengguna terpaksa berpindah-pindah antarbagian (atau membuka manual di dua tab terpisah) untuk sepenuhnya memahami petunjuk tertentu. Ada titik di mana bab ini mengarahkan pengguna ke satu kalimat dalam bagian sebelumnya dengan cara yang memaksa pembaca untuk men-scroll ke atas atau mengikuti {i>hyperlink<i} untuk memahami instruksi yang tepat, karena manual menggunakan bahasa yang tidak jelas seperti "langkah ini ditentukan sebelumnya setelah langkah 11" di bagian sebelumnya. Meskipun metode ini menghilangkan pengulangan, metode ini mempersulit pemahaman petunjuk, karena ini adalah tugas yang perlu dilakukan dalam urutan tertentu. Sebagai gantinya, saya mengusulkan untuk menyertakan kata-kata yang lebih spesifik sehingga pengguna tidak perlu mengganggu proses membaca mereka dengan beralih antar-bagian atau dokumen.
Jika saya menyelesaikan bagian ini sebelum linimasa standar selesai, saya juga ingin membersihkan halaman “Why HPX?” (3) di bawah STE||User Documentation (Dokumentasi Pengguna grup AR). Halaman ini berisi konten pengantar berulang, yang saya harap dapat digabungkan dan berisi inkonsistensi dalam penggunaan huruf besar (terutama jargon) dan gaya bahasa, yang membuatnya terasa tidak terpadu. Sasaran saya adalah membuat perkenalan yang lebih terpadu dan konsisten untuk karya grup STE||AR.