หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ 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 ที่แชร์)