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