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