หน้านี้มีรายละเอียดของโครงการเขียนเชิงเทคนิคที่ยอมรับใน Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- Matplotlib
- ผู้เขียนด้านเทคนิค:
- เยโรเมฟ
- ชื่อโปรเจ็กต์:
- การพัฒนาเส้นทางเข้าถึงของ Matplotlib
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
เกริ่นนำ
คำแนะนำโครงการของ Matplotlib สำหรับเทศกาลเอกสารของ Google ในปีนี้เกี่ยวข้องกับการสร้างเนื้อหาที่ช่วยแนะนำให้ผู้ใช้รายใหม่รู้จัก Matplotlib สำหรับการพัฒนา Entry Path ของ Matplotlib ฉันขอเสนอแนวทางอื่นแทนเอกสารประกอบปัจจุบัน ฉันเป็นนักเขียนด้านเทคนิคหน้าใหม่ในอุตสาหกรรมนี้ แต่ภูมิหลังของฉันอยู่ในสายการศึกษาและสาขาที่เทียบเคียงกับการศึกษา งานเขียนเชิงเทคนิคและการศึกษาต่างก็มีลักษณะสอดคล้องกันอย่างมาก โดยมุ่งเน้นการผลิตเนื้อหาที่เข้าใจและช่วยให้ผู้ใช้ทำงานสำเร็จด้วยทรัพยากรที่มีให้
ในบริบทนี้ เอกสารประกอบของ Matplotlib จึงจะมีการปรับปรุงให้ความเห็นอกเห็นใจผู้ใช้ใหม่ เนื้อหาส่วนใหญ่ในขณะนี้ประกอบด้วยข้อมูลแบบสุ่มและภาพที่ไม่มีป้ายกำกับ ซึ่งเหมาะสำหรับการแสดงภาพและฟีเจอร์ของ Matplotlib อย่างรวดเร็ว อย่างไรก็ตาม สำหรับกรณีการใช้งานของผู้ที่เพิ่งเริ่มใช้ Matplotlib การข้ามผ่านการแปลงข้อมูลให้เป็นภาพนั้นทำได้ยาก
บริบทในแนวทางแบบอธิบายเป็นทางออกสำหรับอุปสรรคนี้ การเขียนขั้นตอนผ่านมุมมองจากตัวอย่างในโลกแห่งความเป็นจริงถือเป็นการแสดงให้เห็นถึงความเข้าใจในสิ่งแวดล้อมที่ผู้ใช้ทำงาน การทำเช่นนี้จะช่วยปรับปรุงความสัมพันธ์ในเอกสารและผู้ใช้ในแง่ของการบรรลุเป้าหมายหรือความคาดหวังที่จะทำงานให้สำเร็จ
ผู้ใช้มีจุดประสงค์ที่ได้มาที่สอดคล้องกัน เช่น นักวิทยาศาสตร์ข้อมูลของบริษัทรองเท้าแห่งหนึ่งต้องนำเสนอข้อมูลลูกค้าแก่ทีมเพื่ออธิบายเทรนด์การช็อปปิ้งเมื่อเวลาผ่านไป ในกรณีนี้ ผู้ใช้ต้องเรียนรู้วิธีไปยังส่วนต่างๆ ของ Matplotlib และใช้ประโยชน์จากเครื่องมือภายในไลบรารีเพื่อทำงานให้เสร็จ
หากมีบริบทเพิ่มเติมเพื่อสนับสนุนเอกสารประกอบ ผู้ใช้ใหม่อาจระบุหัวข้อได้ง่ายขึ้น วัตถุประสงค์ของผู้ใช้จะควบคู่ไปกับเอกสารประกอบ ฉันหวังว่าจะทำตามวิสัยทัศน์ที่หัวหน้านักพัฒนาอย่าง Tom Caswell พูดถึงในการให้สัมภาษณ์เมื่อปี 2017 ว่า "การมีคนที่เขียนได้จริงและเห็นอกเห็นใจผู้ใช้ คอยเขียนหนังสือ "Intro to Matplotlib" ความยาว 200 หน้า และเป็นเหมือนข้อความหลักในเอกสาร"
ทางเลือกอื่นของการเขียนเชิงเปิดเผย
เอกสารปัจจุบันแสดงฟีเจอร์ของ Matplotlib ซึ่งก็คือสิ่งที่ผู้ใช้ทำกับไลบรารีได้ ตัวอย่างเช่น บทแนะนำมักจะทำตามรูปแบบที่ไม่เกี่ยวข้องกับคำอธิบายของวิธีการเหล่านั้น
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
โดยส่วนใหญ่จะมีเอกสารและการสนับสนุนการเขียนโปรแกรม ระบบแนะนำให้ผู้ใช้เรียกใช้โค้ดด้วยตนเองเพื่อให้เข้าใจสิ่งที่เกิดขึ้น แม้ว่าแนวความคิดการเขียนโปรแกรมจะช่วยให้ผู้ใช้เข้าใจหัวข้อมากขึ้น แต่เส้นโค้งการเรียนรู้สำหรับการเปลี่ยนแปลงกลับมีเนื้อหาสนับสนุนเพียงเล็กน้อย อาจเป็นภารกิจที่ท้าทายจนเกินไป เนื่องจากเรามีเอกสารจํากัด
การมอบแผนภาพ รูปภาพ หรือภาพประกอบเพิ่มเติมจะช่วยสร้างโอกาสใหม่ๆ ในการเรียนรู้ โครงสร้างด้านล่างก็สามารถใช้เป็นเทมเพลตสำหรับเนื้อหาใหม่ได้เช่นกัน นอกจากนี้ จุดเพิ่มรูปภาพหรือกราฟิกที่ไม่ใช่ข้อความอาจใช้ประโยชน์จากฟีเจอร์ต่างๆ เช่น ข้อความไฮไลต์และเครื่องหมายโค้ช บางครั้งรูปภาพก็ไปยังส่วนต่างๆ ได้ยากขึ้นโดยไม่มีตัวบ่งชี้ว่าจะเปลี่ยนรูปแบบโค้ดไปเป็นเอาต์พุตอย่างไรหรือที่ไหน ฉันเชื่อว่าองค์ประกอบภาพที่ชัดเจนนั้นขาดหายไปเพื่อเสริมสร้างความเข้าใจในหัวข้อต่างๆ ให้ดียิ่งขึ้น
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
วิธีการทางเลือกนี้ใช้การเขียนเชิงประจักษ์สำหรับเอกสารประกอบยังมีศักยภาพอีกมากมาย การที่ผู้ใช้ได้เห็นแนวคิดในการเปลี่ยนรูปแบบที่หลากหลาย ผู้ใช้จึงสามารถระบุกลยุทธ์ที่สำคัญในการพัฒนาการแสดงภาพข้อมูลได้ดีขึ้น ความรู้นี้ช่วยให้ผู้ใช้สร้างสรรค์สิ่งใหม่ๆ และใช้ประโยชน์จากฟีเจอร์ต่างๆ ได้ตามตัวอย่างที่ให้ไว้ในกรณีการใช้งานที่สมจริง
เนื่องจาก Matplotlib ได้รับความนิยมมากขึ้น ความสม่ำเสมอในด้านการใช้งานและความสะดวกจึงเป็นข้อพิสูจน์ถึงชื่อเสียงของห้องสมุด โดยคุณลักษณะเหล่านี้จะช่วยสาธิตรูปแบบและกลยุทธ์ทั่วไป ซึ่งไม่เพียงแสดงภายในโค้ดเท่านั้น แต่ยังรวมถึงภายในเอกสารด้วย หาก Matplotlib ไม่ซับซ้อนและเป็นมาตรฐานสำหรับผู้ใช้ในการเขียนโปรแกรมเนื่องจากเห็นได้ชัดเจนว่ามีการใช้ทรัพยากรเพิ่มมากขึ้นและขยายตัว ก็อาจเป็นวิธีนั้นสำหรับการจัดทำเอกสารทางเทคนิค
เมื่อผู้ใช้พบปัญหา เป็นเรื่องปกติที่จะใช้การค้นหาเพื่อแก้ปัญหา แทนที่จะใช้การค้นหาเป็นวิธีหลักในการนำทาง การให้ผู้ใช้สร้างหลักสูตรของตนเองภายในเอกสารประกอบจะให้ผลดีกว่า ดังนั้น ผู้ใช้จึงค้นหาวิธีแก้ปัญหาของตนเอง จากนั้นเมื่อพบปัญหาอื่นหรือต้องการข้อมูลเพิ่มเติม ก็จะใช้ลิงก์ที่ละเอียดและครอบคลุมตลอด
ซึ่งเกี่ยวข้องกับสถาปัตยกรรมจากล่างขึ้นบนในระบบองค์กร สำหรับทุกหัวข้อภายใน Matplotlib เครือข่ายที่เข้มข้นของลิงก์ไปยังผู้สนใจในหัวข้อและหัวข้อที่ให้ข้อมูลจะช่วยสร้างเครือข่ายที่มีประสิทธิภาพ ในเครือข่ายนี้ ผู้ใช้มีแนวโน้มที่จะใช้เอกสารต่อเมื่อไปยังหัวข้อของตนและสำรวจข้อมูลเพิ่มเติมเกี่ยวกับหัวข้อนั้น
อุปสรรค
โครงการจะมีความท้าทายและมีรายละเอียดเช่นนี้อยู่เสมอ ในฐานะนักเขียนรุ่นใหม่ในอุตสาหกรรม ฉันมีประสบการณ์จำกัดในการใช้ Sphinx และ ReST ในการเขียนเอกสารประกอบ การใช้ Matplotlib และ Git ก็เพิ่งหัดทำเหมือนกัน การจัดการกับระบบทั้ง 4 อย่างนี้และการทำความคุ้นเคยกับการใช้งานเพื่อการทำงานร่วมกันและการวิจัยนั้นต้องใช้เวลามาก ฉันต้องจัดสรรเวลาในช่วงสร้างความผูกพันกับชุมชนและเร็วขึ้นเพื่อสร้างรากฐานที่จำเป็นสำหรับเส้นทางของระดับเริ่มต้น ในระหว่างนี้ หากมีปัญหาด้านแนวคิดและหลักการพื้นฐาน ฉันก็จะต้องติดต่อชุมชนเพื่อขอความช่วยเหลือเพิ่มเติม
นอกจากนี้ การประสานงานเพื่อความร่วมมือกันข้ามเขตเวลาและแพลตฟอร์มออนไลน์ต่างๆ จะต้องปรับไปตามสถานการณ์ด้วย มีช่องทางการสื่อสารหลากหลายแบบที่ผู้คนทั่วโลกใช้ ดังนั้นสิ่งสำคัญคือต้องทำให้ฉันเข้าถึงได้และเข้าถึงได้ในทุกสื่อ ฉันจะให้ความสำคัญอย่างโปร่งใสในการให้ความสําคัญกับความคาดหวังต่างๆ ในทุกด้าน แม้ว่าฉันเพิ่งเริ่มใช้งานในลักษณะนี้ในอุตสาหกรรม แต่ฉันก็ทุ่มเทให้กับการรับผิดชอบต่อตัวเอง ตลอดจนเปิดใจรับฟังความคิดเห็นและคำวิจารณ์ ฉันรู้สึกว่าคุณภาพเหล่านี้มีค่าไม่ว่าจะในด้านใดก็ตาม
นอกจากนี้ การเพิ่มการทดสอบความสามารถในการใช้งานยังเป็นส่วนหนึ่งของเอกสารประกอบที่ฉันคิดว่าจะเป็นประโยชน์ต่อเส้นทางการเข้าสู่โปรแกรมของ Matplotlib การทำแบบสํารวจเพื่อความสามารถในการใช้งานในเนื้อหามีไว้เพื่อวัตถุประสงค์ในการนำเสนอโปรไฟล์ของผู้ใช้ เช่น ลักษณะตัวตน ข้อมูล เช่น ประสบการณ์ของผู้ใช้ อุตสาหกรรม และประวัติการแก้ปัญหาของผู้ใช้นั้นมีค่าอย่างยิ่ง ข้อมูลเหล่านี้มีส่วนในการสร้างถ้อยคำที่อยู่เบื้องหลังกระบวนการ เมื่อการเขียนตรงกับผู้อ่านในระดับที่เหมาะสม เนื้อหาจะเหมาะสำหรับผู้อ่านคนอื่นๆ ที่เป็นมากกว่าการสอนเพียงอย่างเดียว
ปัญหาใหญ่มักจะอยู่ที่การสร้างการทดสอบความสามารถในการใช้งานอย่างต่อเนื่อง เป็นเรื่องปกติที่จะมีการทดสอบเพียงรายการเดียวหรือทุกครั้งระหว่างการพัฒนาเนื้อหา การทดสอบความสามารถในการใช้งานเป็นประจำช่วยกระตุ้นการถ่ายทอดเนื้อหา ฉันหวังว่าจะได้กำหนดเวลานัดหมายหรือทดสอบความสามารถในการใช้งานเป็นประจำกับชุมชน Matplotlib
บทสรุป
ฉันมีประสบการณ์เล็กน้อยในการใช้ Python รวมถึง Matplotlib ในเวลาว่าง ฉันได้เรียนรู้สิ่งต่างๆ ด้วยตนเองในช่วง 2-3 เดือนที่ผ่านมามาจากการสนับสนุนจากเอกสารปัจจุบันและความอยากรู้อยากเห็นของฉันเอง มีวิดีโอและที่ปรึกษาจำนวนหนึ่งที่ฉันมีในช่วงเวลานั้นด้วย เพราะฉันยังมีอะไรให้เรียนรู้อีกมากมายและมีพื้นที่สำหรับการปรับปรุงเพิ่มเติมอีกเนื่องจากได้สร้างหลักสูตรการเขียนโปรแกรมของตัวเองและสนใจ
หลังจากได้เห็นไอเดียที่ Matplotlib และชุมชนมีให้กับ GSoD แล้ว ผมรู้สึกว่าสิ่งนี้จะเป็นประสบการณ์ที่ดีเยี่ยมซึ่งช่วยให้พัฒนาทักษะในฐานะนักเขียนเชิงเทคนิคได้ และยังมีโอกาสได้เรียนรู้เพิ่มเติมจากเพื่อนๆ อีกมาก ผมรู้สึกว่าโครงการ Matplotlib นี้มีความหมายและเป็นสิ่งที่ผมหลงใหลในด้านอุดมการณ์
หลังจากปรับเปลี่ยนคู่มือการใช้งานใหม่ เป้าหมายของฉันในฐานะนักเขียนด้านเทคนิคคือการช่วยให้ผู้ใช้ทำสิ่งต่างๆ ที่ต้องการได้โดยไม่รู้สึกกับการใช้ฟีเจอร์ที่มีอยู่มากมาย ผมเชื่อว่าเอกสารที่ดีที่สุดจะยังคงเติบโตและปรับให้เข้ากับผู้ใช้ต่อไป และช่วยให้ผู้ใช้พบโซลูชันของตนเอง