หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- BRL-CAD
- ผู้เขียนด้านเทคนิค:
- ซาฮิบเคาร์
- ชื่อโปรเจ็กต์:
- คู่มือสำหรับผู้เริ่มต้นใช้งาน BRL-CAD
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
คู่มือสำหรับผู้เริ่มต้นใช้งาน BRL-CAD
โปรเจ็กต์นามธรรม
โปรเจ็กต์นี้มีวัตถุประสงค์ในการสร้างเอกสารสำหรับผู้ใช้ที่ไม่เพียงคุ้นเคยกับ BRL-CAD เท่านั้น แต่ยังใหม่กับโอเพนซอร์สด้วย
ทำไมจึงต้องมีโปรเจ็กต์นี้
ตอนที่ฉันเข้าชมเว็บไซต์ BRL-CAD เป็นครั้งแรก เนื่องจากเป็นมือใหม่เกี่ยวกับโอเพนซอร์สและ BRL-CAD ฉันจึงได้ข้อมูลจำนวนมากในทีเดียว แต่ลึกๆ แล้วฉันรู้ว่าที่นี่มีอะไรให้เรียนรู้อีกมากมาย ดังนั้น เราจึงต้องการจัดทำเอกสารสำหรับผู้ใช้ใหม่อย่างฉันเพื่อให้ได้รับประโยชน์สูงสุดจากชุมชนนี้ และรู้สึกสบายใจที่จะเริ่มต้นใช้งาน
ยิงประตู
โปรเจ็กต์นี้จะกำหนดเป้าหมายเป็นผู้ใช้ใหม่ ดังนั้น เป้าหมายบางส่วนที่เอกสารประกอบของฉันตั้งเป้าไว้มีดังนี้ เพื่อให้ผู้ใช้ใหม่รู้สึกสบายใจ: เอกสารประกอบนี้มีไว้สำหรับผู้ใช้ใหม่ ไม่เพียงแต่เพิ่งเริ่มใช้ BRL-CAD แต่ยังเป็นมือใหม่ในการใช้โอเพนซอร์สด้วย
เพื่อให้บรรลุเป้าหมายนี้ ฉันจะดำเนินการดังนี้
- ตรวจสอบว่าคะแนน Flesch-Kincaid ของเอกสารไม่ต่ำกว่า 50 คะแนน ตามวิธีการของ Flesch-Kincaid ยิ่งคะแนนสูงเท่าใด ก็ยิ่งเข้าใจง่ายขึ้นเท่านั้น คุณตรวจสอบคะแนนความอ่านได้ง่ายทางออนไลน์
- ใช้รายการสัญลักษณ์แสดงหัวข้อย่อยหรือรายการที่เรียงลำดับเลขเพื่อให้ผู้อ่านไม่เบื่อหรือเสียสมาธิไปกับย่อหน้ายาวๆ
- ใช้ย่อหน้าและประโยคที่สั้นลง เนื่องจากต้องใช้จิตวิญญาณมากขึ้นในการอ่านและทำความเข้าใจประโยคที่ยาว
- ใช้หัวข้อย่อยเพื่อแบ่งข้อความ เอกสารประกอบที่มีโครงสร้างดี: เอกสารที่มีโครงสร้างดีมีบทบาทสำคัญในการแนะนำผู้ใช้ใหม่ เพื่อป้องกันไม่ให้หลงทาง และแจ้งให้พวกเขารู้ว่าตนกำลังมุ่งหน้าไปไหนและทำอะไรอยู่ ฉันจึงได้สร้างแผนที่ความคิดคร่าวๆ ที่จะช่วยให้เราบันทึกคู่มือสำหรับผู้เริ่มต้นใช้งานได้อย่างเป็นระเบียบ
คำอธิบายโครงการ
โครงการนี้เน้นการเขียนเอกสารประกอบเพื่อให้ผู้ใช้ใหม่ได้ใช้ซอฟต์แวร์นี้
ด้านล่างนี้เป็นตัวอย่างของวิธีที่เราตั้งใจจะทำให้เอกสารอธิบายได้ชัดเจนขึ้น
บทนำเบื้องต้น: BRL-CAD (อ่านว่า be-are-el-cad) คือการออกแบบรูปเรขาคณิตที่มั่นคง (CSG) ของ Solid Modeling โดยใช้คอมพิวเตอร์ (CAD) โดยเป็นระบบการสร้างแบบจำลองที่มั่นคงพร้อมแบบโอเพนซอร์สข้ามแพลตฟอร์ม สำหรับการออกแบบโดยใช้คอมพิวเตอร์ช่วยและการแสดงข้อมูลผ่านภาพ 3 มิติ หากไม่อยากคิดถึง มาดูรายละเอียดกัน โอเพนซอร์ส: ซอฟต์แวร์โอเพนซอร์สคือซอฟต์แวร์ที่มีซอร์สโค้ดซึ่งใครๆ ก็ตรวจสอบ แก้ไข และปรับปรุงได้ BRL-CAD เป็นซอฟต์แวร์โอเพนซอร์สที่ต้อนรับคุณเข้ามามีส่วนร่วม และทำให้ BRL-CAD ดีกว่าเดิม การออกแบบโดยใช้คอมพิวเตอร์ (CAD): อธิบายง่ายๆ ก็คือ CAD คือการใช้โปรแกรมคอมพิวเตอร์ในการสร้างภาพกราฟิกที่แสดงวัตถุทางกายภาพสองหรือสามมิติ ระบบการสร้างแบบจำลองที่มั่นคง: BRL-CAD มุ่งเน้นการสร้างแบบจำลอง CAD ที่มั่นคง การสร้างแบบจำลองที่มั่นคงแตกต่างจากการสร้างโมเดลรูปทรงเรขาคณิตอื่นๆ โดยเน้นที่ความถูกต้องแม่นยำทางกายภาพ ซึ่งอธิบายพื้นที่ 3 มิติอย่างสมบูรณ์ จำลองวัตถุทั้งภายในและภายนอก Constructive Solid Geometry (CSG): CSG ทำให้สามารถแสดงโมเดลที่ซับซ้อนเป็นชุดการดำเนินการบูลีนระหว่างสูตรพื้นฐาน วัตถุที่เป็นของแข็งที่สุดที่ใช้สำหรับการนำเสนอเรียกว่าวัตถุพื้นฐาน โปรดไปที่นี่เพื่อทำความเข้าใจเกี่ยวกับ CSG ในระดับพื้นฐาน
*ดังที่ได้กล่าวไว้ในคำอธิบายแนวคิดของโครงการ: เอกสารประกอบเพียงเล็กน้อยจะครอบคลุมเรื่องการติดตั้งขั้นพื้นฐาน คำอธิบายความสามารถโดยรวม หลักการการสร้างแบบจำลองของ BRL-CAD การใช้เครื่องมือหลักพื้นฐาน การสร้างแบบจำลอง การนำเข้า/ส่งออก การวิเคราะห์ และการแสดงผล
รายการต่อไปนี้เป็นการแนะนำสั้นๆ เกี่ยวกับวิธีที่เราจะกล่าวถึงแต่ละส่วนในเอกสารประกอบ
- การติดตั้งขั้นพื้นฐาน: ฉันจะเพิ่มบทแนะนำทีละขั้นตอนในการติดตั้งซอฟต์แวร์ BRL-CAD พร้อมกับภาพหน้าจอที่ต้องใช้ บทแนะนำสำหรับมือใหม่เป็นจุดเริ่มต้นที่ดีสำหรับผู้ใช้ใหม่ ฟีเจอร์บางอย่างที่เราพบว่าขาดหายไป ได้แก่
- ขั้นตอนในบทแนะนำของผู้เริ่มต้นใช้งานรายนี้ไม่ได้ใช้สัญลักษณ์แสดงหัวข้อย่อยหรือใส่หมายเลข การดูบทแนะนำแบบทีละขั้นตอนพร้อมภาพหน้าจอที่ตอนท้ายของแต่ละขั้นตอนจะช่วยให้ผู้ใช้อยากดูบทแนะนำนี้มากขึ้น
- คำอธิบายความสามารถโดยรวม: ส่วนนี้จะครอบคลุมความสามารถทั้งหมดที่ BRL-CAD มีอำนาจในการแสดงสิ่งมหัศจรรย์ แผนภาพเป็นวิธีที่ดีกว่าในการดึงดูดความสนใจในส่วนนี้
- หลักการการสร้างรูปแบบของ BRL-CAD: ส่วนนี้จะต้องอธิบายเพิ่มเติม เนื่องจากผู้ใช้จะเข้าใจ BRL-CAD ได้ดีขึ้น เมื่อพวกเขาเข้าใจหลักการการสร้างรูปแบบเหล่านี้อย่างถ่องแท้แล้ว
- การใช้งานพื้นฐานของเครื่องมือหลักๆ: ในส่วนนี้ เราจะมีบทแนะนำแยกต่างหากสำหรับเครื่องมือหลักๆ และการใช้งานเบื้องต้น วิดีโอเหล่านี้จะเป็นบทแนะนำแบบทีละขั้นตอน
- ส่งออก/นำเข้า: ผู้ใช้จะได้รู้จักกับไลบรารี Conversion เรขาคณิต หนึ่งในการใช้งานที่พบบ่อยที่สุดของ BRL-CAD คือการแปลงเรขาคณิตจากรูปแบบหนึ่งเป็นอีกรูปแบบหนึ่ง ในส่วนนี้ เราจะกล่าวถึงเครื่องมือส่งออกและนำเข้า Conversion
- การแสดงภาพ: เราจะพูดถึงข้อมูลเบื้องต้นเกี่ยวกับการแสดงผลและความจำเป็นในการแสดงผลภาพในซอฟต์แวร์ของเรา ผู้ใช้จะได้รับทราบวิธีแสดงผลรูปภาพในสกุลเงิน BRL-CAD อีกด้วย
นอกจากนี้ ยังให้ความสำคัญกับประเด็นต่อไปนี้ด้วย
- ในช่วงต้นของเอกสารประกอบจะมีความเข้าใจเบื้องต้นว่าซอฟต์แวร์นี้เกี่ยวกับอะไร
- ผู้ใช้จะเชื่อมต่อกับชุมชนโอเพนซอร์สนี้ได้อย่างไร ลิงก์ไปยังการแชทของ BRL-CAD zulip
- ในระดับนามธรรม ทำให้เอกสารดูตลกขบขันเล็กน้อยและถามผู้ใช้ใหม่ว่าอย่าหมดกำลังใจกับคำสำคัญ ฉันชอบแนวทางการเห็นอกเห็นใจซึ่งหน้าที่ใช้ในหน้าหลักของ BRL-CAD wiki
- โดยจะมีภาพหน้าจอของสิ่งที่ผู้ใช้สามารถทำได้เมื่อใช้ซอฟต์แวร์นี้
เหตุการณ์สำคัญ
กรกฎาคม (ระยะเวลาการตรวจสอบข้อเสนอ)
- ฉันจะทำความคุ้นเคยกับซอฟต์แวร์และเอกสาร wiki ของซอฟต์แวร์ ระหว่างที่ดูบทแนะนำที่มีอยู่แล้ว
- เราจะดำเนินการปรับปรุงในเอกสารที่มีอยู่
1 สิงหาคม - 7 สิงหาคม (เสริมสร้างความสัมพันธ์กับชุมชน)
- พูดคุยกับที่ปรึกษาเกี่ยวกับโปรเจ็กต์
- ปรับแต่งรายละเอียดโครงการ
- ทำการเปลี่ยนแปลงที่จำเป็นในเป้าหมาย (หากจำเป็น)
8 สิงหาคม - 14 สิงหาคม
- ทำความคุ้นเคยกับ XML ของเอกสาร
15 สิงหาคม - 21 สิงหาคม
- เอกสารประกอบการเขียนเรื่อง "ข้อมูลเบื้องต้นเกี่ยวกับ BRL-CAD"
- การเขียนบทแนะนำแบบทีละขั้นตอนสำหรับ "การติดตั้งขั้นพื้นฐาน"
22 สิงหาคม - 27 สิงหาคม
- สำรวจความสามารถต่างๆ ของ BRL-CAD และจดไว้พร้อมภาพหน้าจอ
- อธิบายฟีเจอร์แต่ละรายการในหน้าที่แยกต่างหาก
28 สิงหาคม - 3 กันยายน
- ทำงานในเอกสารแต่ละรายการต่อไปเพื่อดูความสามารถต่างๆ
4 กันยายน - 10 กันยายน
- กําลังหาหลักการในการสร้างแบบจำลอง
- อธิบายหลักการสร้างแบบจำลองทั้งหมด
11 กันยายน - 17 กันยายน
- ทำงานกับเครื่องมือสำคัญขั้นพื้นฐาน
- เพิ่มไอเดียในรายการโปรดเพื่อบันทึกการใช้งานพื้นฐานของเครื่องมือแต่ละรายการ
18 กันยายน - 24 กันยายน
- อธิบายการใช้งานเครื่องมือแต่ละรายการ
25 กันยายน - 1 ตุลาคม
- ใช้การสร้างแบบจำลองเพื่อสร้างแบบจำลองที่แข็งแกร่งสำหรับบทแนะนำและเขียนฉบับร่างไปพร้อมกับงาน
2 ตุลาคม - 8 ตุลาคม
- ปรับปรุงแบบร่างการประมาณ
2 ตุลาคม - 8 ตุลาคม
- กำลังศึกษาเครื่องมือแปลงและนำเข้าสำหรับการส่งออก
9 ตุลาคม - 15 ตุลาคม
- เตรียมการส่งออกและนำเข้าเอกสาร
- เริ่มแสดงภาพ
16 ตุลาคม - 22 ตุลาคม
- การบันทึกบทแนะนำการแสดงภาพ
23 ตุลาคม - 29 ตุลาคม
- กำลังตรวจสอบเอกสารทั้งหมด
30 ตุลาคม - 5 พฤศจิกายน
- การทำงานกับ XML ของเอกสาร
6 พฤศจิกายน - 12 พฤศจิกายน
- ขอรับความเห็นจาก Mentor และสมาชิกชุมชนคนอื่นๆ แล้วดำเนินการแก้ไข
- พูดคุยกับที่ปรึกษาและทำการเปลี่ยนแปลงขั้นสุดท้าย
12 พฤศจิกายน - 22 พฤศจิกายน
- กระบวนการพูดคุยและการเปลี่ยนแปลง
- สรุปเป็นครั้งสุดท้ายเกี่ยวกับเอกสาร
เกี่ยวกับฉัน
ฉันมีส่วนร่วมในการเขียนมาตั้งแต่สมัยเรียน ฉันจะกลับมาจากโรงเรียนและเขียนถึงวันนี้ ว่าชีวิตดีขึ้นหรือแย่ลง ฉันใฝ่ฝันที่จะจดข้อผิดพลาดที่ทำอยู่และวิธีปรับปรุงข้อผิดพลาดนั้นอยู่เสมอ
ระหว่างการฝึกเป็นนักออกแบบเว็บ เราถูกขอให้จดบันทึกสิ่งที่เราเรียนรู้ในแต่ละวัน ฉันจะบันทึกปัญหาที่พบและวิธีแก้ไข
ในฐานะคนๆ หนึ่ง ฉันพยายามอย่างเต็มที่เพื่อช่วยเหลือผู้อื่น ในช่วงที่โรงเรียนและมหาวิทยาลัย ผมจะอธิบายให้เพื่อนๆ ฟังหลังจากที่เข้าใจหัวข้อนั้นด้วยตนเอง การเข้าร่วมใน GSoD เป็นขั้นตอนที่ยอดเยี่ยมซึ่งฉันในฐานะนักเขียนสามารถช่วยให้ชุมชนโอเพนซอร์สนี้น่าสนใจและมีประโยชน์มากขึ้นสำหรับผู้ใช้ใหม่ทั่วโลก