หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- SciPy
- ผู้เขียนด้านเทคนิค:
- mkg33
- ชื่อโปรเจ็กต์:
- เอกสารที่เน้นผู้ใช้และการปรับโครงสร้างอย่างละเอียด
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
แรงจูงใจ:
ฉันตั้งใจที่จะดำเนินการปรับเปลี่ยนโครงสร้างเอกสารที่มีอยู่เพื่อให้ผู้ใช้ที่มีความต้องการต่างกันสามารถเข้าถึงได้อย่างง่ายดาย ไม่ต้องบอกก็รู้ว่านักวิจัยมักจะสนใจฟีเจอร์ขั้นสูงและแบบละเอียด ส่วนผู้ใช้ที่ไม่มีความเชี่ยวชาญมาก่อนก็ชอบคำแนะนำทีละขั้นตอนและแผนภาพ
ฉันสนใจที่จะดำเนินโปรเจ็กต์นี้ด้วยเหตุผลทั้งส่วนตัวและทางการทำงาน อย่างแรกเลยฉันอยากจะมีส่วนร่วมอย่างมากกับ SciPy เพราะงานวิจัยของฉันเองได้รับประโยชน์อย่างมาก อย่างที่สองคือฉันพบเอกสารประกอบไม่เพียงพอ (หรือขาด) ในซอฟต์แวร์อื่นบ่อยเกินไป และมักสงสัยเสมอว่าผู้ใช้จะเรียนรู้วิธีใช้โค้ดได้อย่างไรและได้รับคำแนะนำอย่างละเอียด
เป้าหมาย
ฉันมุ่งมั่นที่จะปรับปรุงเอกสารประกอบ SciPy ที่มีอยู่ทั้งในด้านเนื้อหาและกราฟิก คุณลักษณะที่สำคัญที่สุดของแนวทางสำหรับปัญหานี้คือการติดตั้งใช้งานและการวิเคราะห์แบบสำรวจผู้ใช้ กล่าวคือ แบบสำรวจที่สั้นกระชับทางออนไลน์ ซึ่งช่วยให้ผู้ใช้ต่างๆ แสดงความคิดเห็นเกี่ยวกับเอกสารประกอบ ฉันเชื่อมั่นอย่างยิ่งว่าความคิดเห็นของพวกเธอควรเป็นแรงบันดาลใจ (เราจะสร้างเอกสารที่ใช้งานง่ายขึ้นได้อย่างไร)
ในส่วนของการเข้าสู่ตัวโครงการ ระยะแรกจะเกี่ยวข้องกับการออกแบบและวิเคราะห์แบบสำรวจผู้ใช้ ตลอดจนแก้ไขปัญหาเกี่ยวกับสไตล์การเขียนที่ผมสังเกตเห็นในเอกสารแนะนำฉบับปัจจุบัน ตัวอย่างเช่น ความไม่สอดคล้องกัน (เช่น อาร์เรย์ 2 มิติที่เกิดขึ้นควบคู่กับอาร์เรย์ 2 มิติ) ประโยคที่ซับซ้อนซึ่งควรเขียนใหม่ หรือการขาดลำดับตัวอักษรในหน้าเว็บย่อยบางหน้า ขั้นที่ 2 จะเน้นที่การแนะนำคู่มือแบบกราฟิกซึ่งมีไฮเปอร์ลิงก์ไปยังหัวข้อที่เกี่ยวข้อง (โดยอิงตามผลการสำรวจและคำขออื่นๆ ของชุมชน) ในระยะยาว เราต้องการให้จัดทำเอกสารที่น่าพึงพอใจสำหรับผู้ใช้แต่ละประเภทโดยเฉพาะ นอกจากนี้ ฉันจะพยายามแสดงบทแนะนำให้สอดคล้องกันมากขึ้นทั้งในภาษาภาษาศาสตร์และเชิงโครงสร้าง สุดท้ายแต่ไม่ท้ายสุด ผมตั้งเป้าที่จะเขียนบทแนะนำใหม่ๆ (ตามความต้องการของชุมชนในปัจจุบัน)
แบบสำรวจผู้ใช้:
ในส่วนของการสำรวจผู้ใช้ ผมเสนอให้ใช้ Google ฟอร์มด้วยเหตุผลหลายประการด้วยกัน เหนือสิ่งอื่นใด Google ฟอร์มเป็นบริการฟรีและมีฟังก์ชันการทำงานแบบไม่จำกัด (ในแง่ของจำนวนผู้ตอบ คำถาม ฯลฯ) มีรูปแบบของภาพที่น่าสนใจ ตัวเลือกแบบสำรวจที่มีประโยชน์มากที่สุด (เช่น ปรับขนาดได้แบบเส้นตรง ช่องทำเครื่องหมาย และคำตอบหลายตัวเลือก) และที่สำคัญที่สุดคือสามารถส่งออกผลลัพธ์ได้อย่างง่ายดายเพื่อวัตถุประสงค์ในการวิเคราะห์ทางสถิติ จากการวิจัยทางออนไลน์ ปรากฏว่า Google ฟอร์มเป็นเครื่องมือฟรีที่ดีที่สุดสำหรับการทำแบบสอบถามในปัจจุบัน เมื่อพูดถึงสิ่งที่ไม่จริงจัง การใช้ผลิตภัณฑ์ Google ในโครงการริเริ่มที่ดำเนินการโดย Google ก็เป็นสิ่งที่ดี
ฉันได้สร้างแบบสำรวจเบื้องต้นพร้อมคำถามตัวอย่าง (เข้าถึงได้ที่ https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform) จำนวนคำถามที่สมเหตุสมผลในเวอร์ชันสุดท้ายควรอยู่ระหว่าง 10 ถึง 15 ข้อ เพื่อให้ได้ผลลัพธ์ที่เป็นรูปธรรม เราขอแนะนำให้ใช้คำถามแบบหลายตัวเลือก สเกลเชิงเส้น และช่องทำเครื่องหมาย 2-3 ช่องเป็นหลัก สเกลเชิงเส้นไม่ควรมีลักษณะคล้ายคลึงกับสเปกตรัมทั้งหมด (เพราะทําให้เกิดความสับสนและมีแนวโน้มที่จะเกิดการกระจายตัวสูง) จะต้องมีคำถามปลายเปิดไม่เกิน 2 ข้อ ไม่เช่นนั้นผลลัพธ์จะกระจัดกระจายมากและไม่มีประโยชน์เลย ฉันคิดว่าแม้แต่คำตอบในปริมาณที่สูงมากก็ไม่เป็นปัญหา เพราะสามารถส่งออกและวิเคราะห์ข้อมูลได้อย่างง่ายดายโดยอัตโนมัติด้วยซอฟต์แวร์ทางสถิติ หากสมมติว่าจำนวนคำตอบนั้นสูงมาก การวิเคราะห์คำถามปลายเปิดอาจใช้เวลาสักหน่อย แต่เราคิดว่าคงไม่มากจนเกินไป อย่างไรก็ตาม ผู้ใช้ทั่วไปไม่มีแนวโน้มที่จะเขียนเรียงความเกี่ยวกับสถานะของเอกสาร ในกรณีที่แย่ที่สุด คำตอบบางข้อสามารถเก็บเอาไว้เพื่อการวิเคราะห์ในอนาคตได้
คู่มือแบบกราฟิก:
วิสัยทัศน์ของฉันเกี่ยวกับคู่มือแบบกราฟิก (มีจุดประสงค์เพื่อใช้เป็นเครื่องมือนำทาง) ตั้งอยู่บนพื้นฐานยอดนิยมที่ว่ามนุษย์ (ส่วนใหญ่) ประมวลผลโครงสร้างภาพที่ตรงไปตรงมามากกว่าการประมวลผลข้อมูลที่เป็นข้อความเพียงอย่างเดียว ยิ่งไปกว่านั้น แผนภาพที่มีธีมซึ่งเน้นหัวข้อและเส้นเชื่อมหัวข้อความสนใจที่คล้ายกันนั้นเป็นชิ้นงานที่มีคุณค่าสูงสำหรับผู้ใช้ที่ไม่ค่อยมีประสบการณ์ (และไม่เพียงเท่านั้น)
ในส่วนของรายละเอียดการใช้งาน เราขอเสนอให้ใช้แพ็กเกจ TikZ อันดับแรกเลยคือเครื่องมือที่มีประสิทธิภาพสูงและดูเหมือนจะไม่มีความเสี่ยงที่จะเลิกใช้งานในเร็วๆ นี้ นอกจากนี้ยังให้ผลงานคุณภาพสูง มีเอกสารประกอบครบถ้วน และเป็นหัวข้อที่พบเห็นได้บ่อยใน TeX StackExchange และฟอรัมที่ได้รับความนิยมอื่นๆ สิ่งสำคัญที่สุดคือ การผสานรวมไฟล์ TikZ (กล่าวคือ ไฮเปอร์ลิงก์จำนวนมากที่อยู่ในนั้น) กับเอกสาร HTML ไม่ได้ก่อให้เกิดปัญหาสำคัญ เนื่องจากมีแพ็กเกจที่หลากหลาย และการแก้ไขสำหรับการฝังภาพ TikZ ใน HTML (เช่น TeX4ht)
ข้อสงสัยเกี่ยวกับการบำรุงรักษาคู่มือใน SciPy ในอนาคตสามารถแก้ได้ง่ายๆ โดยใช้ Overleaf (อำนวยความสะดวกในการทำงานร่วมกัน และแสดงพรีวิวทันที) และเทมเพลตที่กำหนดไว้ล่วงหน้าที่เราจะส่งให้ โดยพื้นฐานแล้ว เส้นนำที่เป็นกราฟิกไม่ได้มีความแตกต่างกันมากนัก โครงสร้าง ชุดสี และรูปร่างต่างๆ จะมีค่าคงที่แตกต่างกันไป ดังนั้นจะมีการปรับรูปโฉมใหม่และการปรับแต่งเพิ่มเติมในภายหลังจึงไม่เป็นปัญหา
(โปรดดูข้อเสนอเวอร์ชันเต็ม ซึ่งอยู่ในโฟลเดอร์ GSoD ที่แชร์)