หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส
- HPX
- นักเขียนเชิงเทคนิค
- rstobaugh
- ชื่อโปรเจ็กต์:
- แก้ไขและปรับปรุงเอกสาร HPX ที่มีอยู่
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ข้อเสนอของเราคือการแก้ไขและปรับปรุงเนื้อหาของเอกสารประกอบ HPX ที่มีอยู่ ข้อเสนอของเราเป็นโครงการที่มีระยะเวลามาตรฐาน (3 เดือน) ซึ่งมุ่งเน้นที่การแก้ไข 2 บทของ STE||คู่มือของกลุ่ม AR ได้แก่ ""ระบบบิลด์และการเปิดใช้งาน HPX"" (1) และ ""การกำหนดค่าแอปพลิเคชัน HPX"" (2)
บท "ระบบการคอมไพล์และการเปิดใช้งาน HPX" มีข้อผิดพลาดทางไวยากรณ์หลายประการ รวมถึงมีภาษาที่ทำให้สับสนและการใช้อักษรตัวพิมพ์ใหญ่ของคำอย่าง"CMake" ที่ไม่สอดคล้องกัน นอกจากนี้ ยังมีข้อมูลที่ซ้ำกันด้วย เราจึงวางแผนที่จะจัดเรียงใหม่ รวม และตัดให้สั้นลงตามความจำเป็น แม้ว่าบท ""การกำหนดค่าแอปพลิเคชัน HPX"" จะมีข้อผิดพลาดทางไวยากรณ์เล็กน้อยที่ต้องแก้ไข แต่ข้อกังวลหลักของฉันสำหรับบทนี้คือความยากง่ายในการใช้งาน บทนี้มีประเด็นด้านการออกแบบหลักๆ 3 ประการที่เราวางแผนจะแก้ไข
ส่วนหัวบางรายการอยู่ภายในข้อความ ทำให้อ่านบทต่างๆ ได้ยาก ปัจจุบัน ผู้ใช้จะต้องอ่านคู่มืออย่างละเอียดเพื่อให้เข้าใจวัตถุประสงค์ของแต่ละตาราง ผู้ใช้ส่วนใหญ่ไม่ได้โต้ตอบกับคู่มือการใช้งานด้วยวิธีนี้ โดยเฉพาะในกรณีที่เคยอ่านเนื้อหามาก่อนแล้ว แต่เราวางแผนที่จะตรวจสอบว่าแต่ละตารางมีส่วนหัวที่ชัดเจนและแตกต่างกัน ซึ่งผู้ใช้จะมองเห็นได้ง่ายหากเลื่อนดูข้อความ
เมื่อแสดงพร็อพเพอร์ตี้ต่างๆ ในส่วนหัวหนึ่งๆ พร็อพเพอร์ตี้เหล่านั้นไม่ได้เรียงตามลําดับที่สมเหตุสมผล แม้ว่าระบบจะจัดกลุ่มพร็อพเพอร์ตี้ไว้ด้วยกันภายใต้ธีมที่คล้ายกัน แต่ไม่มีการจัดกลุ่มย่อย ซึ่งทำให้ข้อมูลดูกระจัดกระจาย เช่น ผู้ใช้อาจพบพร็อพเพอร์ตี้หลายรายการที่เกี่ยวข้องกับสถานที่ตั้ง พร็อพเพอร์ตี้ 2-3 รายการที่เกี่ยวข้องกับเรื่องอื่น และพร็อพเพอร์ตี้อีกรายการที่เกี่ยวข้องกับสถานที่ตั้ง การไม่มีโครงสร้างภายในในส่วนหัวนี้ทำให้ค้นหาข้อมูลทั้งหมดในหัวข้อย่อยที่เฉพาะเจาะจงได้ยากขึ้น เราจึงวางแผนที่จะจัดระเบียบแผนภูมิหลายรายการใหม่เพื่อจัดกลุ่มข้อมูลที่คล้ายกันไว้ด้วยกันภายใต้หัวข้อแต่ละหัวข้อให้ชัดเจนยิ่งขึ้น
ผู้ใช้ต้องเลื่อนไปมาระหว่างส่วนต่างๆ (หรือเปิดคู่มือใน 2 แท็บแยกกัน) เพื่อให้เข้าใจวิธีการบางอย่างอย่างถ่องแท้ มีบางจุดที่บทจะนําผู้ใช้ไปยังประโยคเดียวภายในส่วนก่อนหน้าในลักษณะที่ทําให้ผู้อ่านต้องเลื่อนขึ้นหรือไปที่ไฮเปอร์ลิงก์เพื่อทําความเข้าใจวิธีการนั้นๆ เนื่องจากคู่มือจะใช้ภาษาที่คลุมเครือ เช่น "ขั้นตอนนี้สร้างขึ้นหลังจากขั้นตอนที่ 11" ในส่วนก่อนหน้า แม้ว่าวิธีการนี้จะลดการทำซ้ำ แต่จะทำให้เข้าใจวิธีการได้ยากขึ้น เนื่องจากงานเหล่านี้เป็นงานที่ต้องทำล่วงหน้าตามลำดับที่ระบุไว้ แต่ขอแนะนำให้ใช้คำที่เจาะจงมากขึ้น เพื่อให้ผู้ใช้ไม่ต้องขัดจังหวะกระบวนการอ่านด้วยการสลับระหว่างส่วนหรือเอกสาร
หากเราเขียนส่วนเหล่านี้เสร็จก่อนไทม์ไลน์มาตรฐานจะสิ้นสุดลง เราต้องการแก้ไขหน้า "เหตุผลที่ควรใช้ HPX" (3) ในส่วนเอกสารประกอบสำหรับผู้ใช้ของกลุ่ม STE||AR ด้วย หน้านี้มีเนื้อหาแนะนำที่ซ้ำกัน ซึ่งเราหวังว่าจะรวมเข้าด้วยกัน และมีความไม่สอดคล้องในการขึ้นต้นด้วยอักษรตัวพิมพ์ใหญ่ (โดยเฉพาะคำศัพท์เฉพาะ) และน้ำเสียง ซึ่งทำให้เนื้อหาดูไม่สอดคล้องกัน เป้าหมายของฉันคือสร้างการแนะนำงานของกลุ่ม STE||AR ให้มีความเป็นหนึ่งเดียวและสอดคล้องกันมากขึ้น