หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs
สรุปโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- SciPy
- นักเขียนเชิงเทคนิค:
- mkg33
- ชื่อโปรเจ็กต์:
- เอกสารประกอบที่มุ่งเน้นผู้ใช้และการปรับโครงสร้างอย่างละเอียด
- ระยะเวลาของโปรเจ็กต์
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
แรงจูงใจ
เราตั้งใจที่จะทําการรีแฟกทอริงเอกสารประกอบที่มีอยู่เพื่อให้ผู้ใช้ที่มีความต้องการแตกต่างกันเข้าถึงเอกสารประกอบดังกล่าวได้ง่าย ไม่ต้องสงสัยเลยว่านักวิจัยมีแนวโน้มที่จะสนใจฟีเจอร์ขั้นสูงและซับซ้อน ในขณะที่ผู้ใช้ที่ไม่มีความเชี่ยวชาญมาก่อนจะชื่นชอบคำแนะนำแบบทีละขั้นตอนและแผนภาพ
ฉันสนใจที่จะทำโปรเจ็กต์นี้ต่อด้วยเหตุผลส่วนตัวและเหตุผลด้านอาชีพ เหตุผลแรกคือฉันอยากมีส่วนร่วมอย่างมากใน SciPy เนื่องจากงานวิจัยของฉันได้รับประโยชน์อย่างมากจาก SciPy และเหตุผลที่ 2 คือฉันพบเอกสารประกอบที่ไม่เพียงพอ (หรือไม่มี) ในซอฟต์แวร์อื่นๆ บ่อยครั้งมาก และมักจะสงสัยว่าผู้ใช้จะเรียนรู้วิธีใช้โค้ดได้เร็วขึ้นเพียงใด (หากมี) หากมีคู่มือที่ละเอียด
เป้าหมาย
เรามุ่งมั่นที่จะปรับปรุงเอกสารประกอบ 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 ที่แชร์)