รายงานกรณีศึกษาปี 2021

ระยะปัจจุบัน:
โปรแกรม Season of Docs ปี 2021 จบลงแล้วเมื่อวันที่ 14 ธันวาคม 2021 ดูไทม์ไลน์

หมายเหตุ: รายงานนี้สรุปข้อมูลจากใบสมัครเข้าร่วมโปรแกรมเดิมและจากกรณีศึกษาสุดท้ายขององค์กร กรณีศึกษาทั้งหมดมีลิงก์มาจากหน้าผลการค้นหาฤดูกาล 2021 ของเอกสาร

เกี่ยวกับซีซันของเอกสาร

Season of Docs เป็นโปรแกรมเพื่อความยั่งยืนที่จัดการโดยสำนักงานโปรแกรมโอเพนซอร์สของ Google เป้าหมายของซีซันของเอกสารคือ:

• ให้การสนับสนุนโครงการโอเพนซอร์สเพื่อแก้ไขปัญหาโครงการด้วยเอกสารประกอบ
• ให้โอกาสนักเขียนด้านเทคนิคได้มีประสบการณ์ในโอเพนซอร์ส
• เพิ่มการรับรู้เกี่ยวกับโอเพนซอร์ส เอกสารประกอบ และการเขียนเชิงเทคนิค
• รวบรวมและแชร์ข้อมูลเกี่ยวกับเมตริกที่มีประสิทธิภาพในเอกสารโอเพนซอร์ส

ดูข้อมูลเพิ่มเติมเกี่ยวกับซีซันของเอกสารในเว็บไซต์ของโปรแกรม

ภาพรวมของโปรแกรมปี 2021

การเปลี่ยนแปลงของโปรแกรมปี 2021

ในปี 2019 และ 2020 องค์กรและนักเขียนด้านเทคนิคต่างก็สมัครเข้าร่วม Season of Docs แยกกัน และผู้ดูแลระบบโปรแกรม Season of Docs ได้จับคู่กับผู้เขียนด้านเทคนิคกับองค์กร องค์กรต่างๆ จัดหาที่ปรึกษาให้ทำงานร่วมกับนักเขียนด้านเทคนิค ซึ่งได้รับเงินสนับสนุนจากการทำงานโดยอิงตามสถานที่ โปรแกรมวัดว่าผู้เขียนด้านเทคนิค ที่ปรึกษา และผู้ดูแลระบบองค์กรพึงพอใจกับการเข้าร่วมโปรแกรมหรือไม่ แต่ไม่ได้วัดผลลัพธ์ของเอกสารประกอบ

ในปี 2021 ทีม Season of Docs ได้ทำการเปลี่ยนแปลงที่สำคัญในโปรแกรม โดยเปลี่ยนมามุ่งเน้นที่การวัดผลลัพธ์ของเอกสารประกอบ และเพิ่มความยืดหยุ่นให้กับองค์กรและนักเขียนด้านเทคนิค

• องค์กรที่ใช้กับข้อเสนอโปรเจ็กต์ รวมถึงงบประมาณและเมตริกที่เสนอ
• ผู้เขียนด้านเทคนิคไม่ได้สมัครผ่าน Google เพื่อจับคู่กับองค์กรอีกต่อไป แต่สมัครโดยตรงกับองค์กรที่ยอมรับ
• องค์กรที่ยอมรับจะได้รับเงินช่วยเหลือผ่าน Open Collective ซึ่งใช้ในการจ่ายเงินให้นักเขียนเชิงเทคนิค
• องค์กรเป็นผู้กำหนดค่าตอบแทนสำหรับนักเขียนด้านเทคนิค
• องค์กรส่งการประเมินขั้นสุดท้ายและกรณีศึกษา รวมทั้งตอบแบบสำรวจติดตามผล

ผลการวิจัยทั่วไปปี 2021

องค์กร

• การเปลี่ยนแปลงในโปรแกรมปี 2021 ทำให้องค์กรสมัครน้อยลง (เราพบว่ามีองค์กรที่สมัครในปี 2021 น้อยลง 30% เมื่อเทียบกับปี 2020) แต่ผู้ดูแลระบบองค์กรในปี 2021 พอใจกับโปรแกรมมากกว่าผู้ดูแลระบบปี 2020 เล็กน้อย (93% v 91%)

ปัญหา ประเภทเอกสาร และเมตริก

• โครงการส่วนใหญ่เน้นที่การสร้างเอกสารประกอบเพื่อลดภาระของผู้ดูแล (ผ่านการลดปัญหา/คำถาม) และ/หรือกระตุ้นการเข้าร่วมโครงการ (โดยผู้ใช้โครงการหรือผู้มีส่วนร่วม)
  • 50% ขององค์กรที่ได้รับการยอมรับสร้างเนื้อหา "บทแนะนำ" หรือ "วิธีการ"
  • มากกว่า 50% ขององค์กรที่ยอมรับพิจารณาว่าเอกสารปัจจุบันของตนขาดการจัดระเบียบ ไม่เป็นระเบียบ หรือล้าสมัย
• โดยทั่วไปแล้ว โปรเจ็กต์ต่างๆ ต้องการวัดประสิทธิภาพของเอกสารผ่านการโต้ตอบ โดยเฉพาะอย่างยิ่งปัญหาที่หยิบยกขึ้นมาน้อยลงและมีผู้เข้าชมเอกสารและการมีส่วนร่วมในโปรเจ็กต์มากขึ้น
• ข้อมูลจากเดือนพฤศจิกายน 2022 โดยมี 25 จาก 30 โปรเจ็กต์ที่ตอบกลับ:
  • 18 โปรเจ็กต์บอกว่าพวกเขาทำได้ตามเมตริกเดิม
  • มี 5 โปรเจ็กต์ที่ผ่านเมตริกที่แก้ไข
  • 2 โปรเจ็กต์ระบุว่ายังเร็วเกินไปที่จะบอก

การเข้าร่วมโปรแกรม

• การสรรหา การว่าจ้าง และการจ้างนักเขียนด้านเทคนิคเป็นส่วนที่ยากที่สุดของโปรแกรมสำหรับผู้ดูแลระบบองค์กร
• ณ เดือนพฤศจิกายน 2022 โดยมี 24 จาก 30 องค์กรตอบกลับ
  • 18 องค์กรยังคงทำงานร่วมกับนักเขียนด้านเทคนิคประจำซีซันของเอกสาร (ไม่ว่าจะเป็นผู้ร่วมให้ข้อมูลอย่างต่อเนื่องหรือแหล่งข้อมูลที่ช่วยตอบคำถาม)
    • องค์กร 4 แห่งทำงานร่วมกันกับนักเขียนด้านเทคนิค ซีซันของเอกสาร ซึ่งได้รับค่าจ้าง

ไฮไลต์ประจำปี 2021

• หลายโปรเจ็กต์บ่งชี้ว่านักเขียนด้านเทคนิคของตนตั้งใจทำงานโปรเจ็กต์ต่อไปหลังจากสิ้นสุดโปรแกรม Season of Docs
• Metanorma มีนักเขียนด้านเทคนิคที่มีใบรับรองจำนวนมากสมัครเข้ามา จนพบเงินทุนที่ตรงกันเพื่อจ้างนักเขียนเพิ่มมาทำงานร่วมกับนักเขียนประจำซีซันที่ให้การสนับสนุนในเอกสารระหว่างโปรแกรมนี้
• Moja Global พบว่าชุมชนมีส่วนร่วมอย่างมากในเรื่องเอกสารประกอบและจัดตั้งคณะทำงานด้านเอกสารประกอบชุดใหม่เพื่อให้ผู้มีส่วนร่วมจำนวนมากขึ้นได้มีส่วนร่วมในเอกสารประกอบของโครงการ

ข้อมูลสรุปปี 2021

ในปี 2021 มีองค์กรที่สมัครเข้ามา 82 แห่ง และองค์กรโอเพนซอร์ส 30 แห่งได้รับการยอมรับให้เข้าร่วมโปรแกรม (โปรดดูเกณฑ์การเลือกในคู่มือการสร้างแอปพลิเคชัน) ดูรายชื่อองค์กรทั้งหมดที่เข้าร่วมได้ในเว็บไซต์ซีซันของเอกสาร องค์กรที่ได้รับการยอมรับทั้ง 30 แห่งได้ส่งรายงานกรณีศึกษาขั้นสุดท้ายเพื่อเข้าร่วมโปรแกรมปี 2021 ให้เสร็จสมบูรณ์

เกี่ยวกับองค์กร

องค์กรที่เข้าร่วมใน Season of Docs 2021 เป็นตัวแทนของโครงการโอเพนซอร์สที่หลากหลาย กลุ่มประชากรตามรุ่นในปี 2021 มีดังนี้

• โปรเจ็กต์ภาษาขนาดใหญ่ เช่น Julia, Perl และ R
• โครงการด้านการศึกษา ภูมิอากาศ FinTech สุขภาพ บริการห้องสมุด แมชชีนเลิร์นนิง แมสสเปกโตรเมทรี สัญญาสาธารณะ และหุ่นยนต์
• โครงการที่มุ่งเน้นนักพัฒนาซอฟต์แวร์ ซึ่งรวมถึงเครื่องมือ Chaos Engineering, Fuzzers, SDK ของแชทบ็อต, ไปป์ไลน์การวิเคราะห์องค์ประกอบของซอฟต์แวร์, เครื่องมือตรวจสอบประสิทธิภาพ และเครื่องมือการเขียนโปรแกรมแบบภาพ
• โปรเจ็กต์เอกสารประกอบสําหรับเครื่องมือเอกสารประกอบ เช่น Redocly และ Metanorma

โปรเจ็กต์ระบบนิเวศ Python เป็นหมวดหมู่ย่อยที่ใหญ่ที่สุด กลุ่มประชากรตามรุ่นในปี 2021 ประกอบด้วย ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite และ SymPy

เราไม่ได้รวบรวมข้อมูลเมตาใดๆ เกี่ยวกับโครงการ (เช่น วันที่ก่อตั้ง การกระจายทางภูมิศาสตร์ของผู้ร่วมให้ข้อมูล จำนวนผู้สนับสนุน หรือขนาดฐานผู้ใช้)

เราได้ขอให้โปรเจ็กต์ระบุใบอนุญาตโอเพนซอร์สที่โปรเจ็กต์เหล่านั้นใช้

ปัญหาเอกสารประกอบที่ระบุโดยองค์กรในปี 2021 เป็นปัญหาที่พบได้ทั่วไปทั้งในโครงการโอเพนซอร์สและในเอกสารทางเทคนิคทั่วไป

ปัญหาหลักๆ ที่องค์กรคาดหวังว่าจะแก้ไขในโปรแกรมปี 2021 ได้แก่

โปรดทราบว่าองค์กรสามารถรายงานปัญหาเกี่ยวกับเอกสารประกอบหลายรายการได้ โปรดดูข้อมูลที่เฉพาะเจาะจงเพิ่มเติมในหน้าผลการค้นหาซีซันของเอกสาร 2021 ซึ่งลิงก์ไปยังกรณีศึกษาทั้งหมดของแต่ละองค์กร

ประเภทเอกสารที่สร้าง

บทแนะนำเป็นเอกสารประเภทที่มีการพูดถึงมากที่สุดในกรณีศึกษาปี 2021

เอกสารประเภทอื่นๆ ที่กล่าวถึงในกรณีศึกษา ได้แก่ ไปป์ไลน์เอกสารเป็นโค้ด, แผนภาพ, อภิธานศัพท์, คู่มือสไตล์, คำถามที่พบบ่อย, การทำให้เป็นสากล, Codelab, โมเดลเนื้อหา, โมดูล, เอกสารแนวคิด, ข้อความแสดงข้อผิดพลาด, การวิจัยผู้ใช้, Readme, ฐานความรู้

หมวดหมู่เหล่านี้บางส่วนไม่ชัดเจนและโครงการเอกสารเดียวอาจมีประเภทหรือฟีเจอร์เอกสารหลายประเภท

มีหลายๆ โปรเจ็กต์ที่อ้างอิงโดยใช้เฟรมเวิร์ก Diátenabled เป็นแนวทางในการวางแผนประเภทเอกสารประกอบโดยเฉพาะ

โปรดดูข้อมูลที่เฉพาะเจาะจงเพิ่มเติมในหน้าผลการค้นหาซีซันของเอกสาร 2021 ซึ่งลิงก์ไปยังกรณีศึกษาทั้งหมดของแต่ละองค์กร

งบประมาณ

ในปี 2021 คำของบประมาณเฉลี่ยอยู่ที่ $10,200 และค่ามัธยฐานคือ $10,000 มีเพียงสามองค์กรที่ขอและได้รับเงินสนับสนุนสูงสุด ($15,000) และอีกสามองค์กรเป็นการขอเงินช่วยเหลือที่ต่ำที่สุด ($5,000)

เมตริก

โครงการที่ระบุในกรณีศึกษาจะเป็นการวัดเมตริกที่ใช้วัดความสำเร็จของโครงการจัดทำเอกสาร

เมตริกที่เสนอมากที่สุดคือ

เมตริกอื่นๆ ที่เสนอ ได้แก่ ดาวของ GitHub, เวลาที่ใช้ในหน้าเว็บ, Conversion รายชื่ออีเมล, การทดสอบโดยผู้ใช้เชิงคุณภาพ, จำนวนผู้เข้าร่วมในฟอรัม, จำนวนพาร์ทเนอร์/อาสาสมัคร/การผสานรวม

เนื่องจากระยะเวลาสั้นๆ ระหว่างที่ทำโปรเจ็กต์เขียนทางเทคนิคจนเสร็จและส่งกรณีศึกษา กลุ่มประชากรตามรุ่นส่วนใหญ่ในปี 2021 จึงไม่สามารถรวบรวมข้อมูลได้เพียงพอที่จะพิจารณาว่าเมตริกเริ่มต้นตรงตามเมตริกแรกหรือไม่

โปรดดูข้อมูลที่เฉพาะเจาะจงเพิ่มเติมในหน้าผลการค้นหาซีซันของเอกสาร 2021 ซึ่งลิงก์ไปยังกรณีศึกษาทั้งหมดของแต่ละองค์กร

ทำงานร่วมกับนักเขียนด้านเทคนิค

การเปลี่ยนแปลงที่ยิ่งใหญ่ที่สุดของโปรแกรมซีซันของเอกสารในปี 2021 เกี่ยวข้องกับการที่โปรเจ็กต์ต่างๆ ทำงานร่วมกับนักเขียนด้านเทคนิค ในฤดูกาลก่อนหน้านี้ นักเขียนด้านเทคนิคสมัครงานกับ Google โดยตรงและได้รับการจับคู่กับผู้ดูแลระบบโปรแกรมที่มีโครงการต่างๆ และได้รับเงินค่าจ้างแบบคงที่จาก Google โดยตรง

ในปี 2021 นักเขียนด้านเทคนิคได้สมัครเข้าร่วมโครงการโดยตรงและโครงการได้กำหนดงบประมาณสำหรับค่าตอบแทนสำหรับนักเขียนด้านเทคนิค โดยชำระเงินผ่านกองทุน Open Collective ซีซันของเอกสาร

โปรเจ็กต์ส่วนใหญ่ที่เข้าร่วมโปรแกรมปี 2021 มีประสบการณ์ด้านการสรรหาหรือจ้างนักเขียนด้านเทคนิคน้อยมากหรือไม่มีเลย เลยมีโปรเจ็กต์จำนวนมากที่เรียกส่วนนี้ว่ากระบวนการนี้เป็นงานที่ต้องได้รับการสนับสนุนเพิ่มเติม ทีม Season of Docs ได้ตอบความคิดเห็นนี้ว่าได้เพิ่มเอกสารประกอบเกี่ยวกับการสร้างข้อตกลงด้านเทคนิคสำหรับนักเขียนลงในคู่มือโปรแกรม

คำแนะนำเกี่ยวกับการจ้างงาน

เราได้ขอให้โปรเจ็กต์แนะนำโปรเจ็กต์อื่นๆ ที่สนใจเข้าร่วมในซีซันของเอกสาร คำแนะนำเกี่ยวกับการจ้างงานสูงสุดมีดังนี้

• แชร์เอกสารการสรรหาบุคลากรสำหรับนักเขียนด้านเทคนิคให้เร็วที่สุดเท่าที่จะเป็นไปได้ ก่อนที่คุณจะได้รับการยอมรับให้เข้าร่วมโปรแกรม ขอให้ชุมชนของคุณแนะนำผู้สมัครที่เป็นไปได้
• แชร์ภายนอกช่องทางของโปรเจ็กต์ในวงกว้าง ใช้ภาษาที่ไม่แบ่งแยกและส่งเสริมให้ผู้มีภูมิหลังที่ไม่ได้รับโอกาสอย่างเท่าเทียมให้สมัครโดยตรง
• ทำความเข้าใจว่าเครื่องมือใดมีความสำคัญต่อกระบวนการสร้างเอกสารของคุณและสรรหานักเขียนด้านเทคนิคที่มีประสบการณ์โดยใช้เครื่องมือเหล่านั้น
• สร้างความคาดหวังที่ชัดเจนให้กับผู้เขียนด้านเทคนิคเกี่ยวกับผลลัพธ์และเป้าหมาย ช่องทางการสื่อสารและการเช็คอิน ตลอดจนกระบวนการและกำหนดเวลาการชำระเงิน
• ลองลงทุนกับสมาชิกในชุมชนและช่วยให้สมาชิกเติบโตในฐานะนักเขียนด้านเทคนิคโดยใช้ฤดูกาลของนักเขียนด้านเทคนิคให้คำปรึกษาและฝึกสอน
• ใช้งบประมาณมากกว่าที่คาดไว้สำหรับการเริ่มงานเขียนด้านเทคนิค รวมถึงตอบคำถามและการให้การสนับสนุนระหว่างโปรแกรม โดยเฉพาะอย่างยิ่งหากนักเขียนด้านเทคนิคไม่มีประสบการณ์ด้านโดเมนของโครงการมาก่อน
• บันทึกขั้นตอนการสรรหา การว่าจ้าง และการเริ่มงาน เพื่อใช้สำหรับโครงการในอนาคต

(หมายเหตุ: บางโปรเจ็กต์ที่ระบุในกรณีศึกษาที่ทีมคัดเลือกผู้สมัครเป็นนักเขียนด้านเทคนิค)

ปัญหาที่พบได้ทั่วไปในการทำงานร่วมกับนักเขียนด้านเทคนิค

นักเขียนด้านเทคนิคในหลายโปรเจ็กต์ต้องลาออกจากการเนื่องจากโควิดหรืออาการเจ็บป่วยอื่นๆ หรือความรับผิดชอบในครอบครัวที่เกี่ยวข้องกับโรคระบาด บางโปรเจ็กต์รายงานปัญหาการสื่อสารซึ่งเกี่ยวข้องกับเขตเวลาไม่ตรงกันหรือปัญหาการเชื่อมต่ออินเทอร์เน็ต

โปรเจ็กต์พบว่าพวกเขาประเมินความยากลำบากที่เกี่ยวข้องกับการเริ่มต้นใช้งานในชุมชนของตนหรือในการตั้งค่าห่วงโซ่เครื่องมือของเอกสารของโปรเจ็กต์ต่ำเกินไป

บางโครงการมีความล่าช้าในการจ่ายเงินให้กับนักเขียนด้านเทคนิคเนื่องจากปัญหาการธนาคารกับ Open Collective หรือเพราะประเทศบ้านเกิดของนักเขียนมีข้อจำกัดด้านการชำระเงิน

เอกสารของโปรแกรมเกี่ยวกับค่าธรรมเนียม Open Collective ไม่ชัดเจน กล่าวคือ Google รับผิดชอบค่าธรรมเนียมการทำธุรกรรม Open Collective สำหรับการโอนเงินครั้งแรกไปยังโครงการ แต่ไม่เรียกเก็บค่าธรรมเนียมธุรกรรมที่เรียกเก็บโดยช่องทางการชำระเงินอื่นๆ (เช่น ค่าธรรมเนียมการแปลงสกุลเงิน) เราจะพยายามอธิบายเรื่องนี้ให้ชัดเจนยิ่งขึ้นในเอกสารสำหรับโปรแกรมในอนาคต

แบบสำรวจติดตามผล

ในฐานะที่เป็นส่วนหนึ่งของโปรแกรม Season of Docs เราได้ขอให้โปรเจ็กต์ร่วมทำแบบสำรวจติดตามผล โดยมีการส่งแบบสำรวจ 3 รายการในช่วงเดือนพฤษภาคม สิงหาคม และพฤศจิกายน 2022

แบบสำรวจติดตามผลได้ขอให้โปรเจ็กต์ยืนยันว่าลิงก์ข้อเสนอและกรณีศึกษายังคงใช้งานได้อยู่ แบบสำรวจยังมีคำถามเกี่ยวกับความสำเร็จของโครงการ (ตามเมตริกที่ระบุไว้ในกรณีศึกษา) ตลอดจนการมีส่วนร่วมอย่างต่อเนื่องและค่าตอบแทนของนักเขียนด้านเทคนิคของโครงการ

1. คุณยังทำงานร่วมกับนักเขียนด้านเทคนิคสำหรับ Season of Docs อยู่ไหม

1. หากนักเขียนด้านเทคนิคยังทำงานในโปรเจ็กต์อยู่ ผู้เขียนจะได้รับค่าตอบแทนด้วยวิธีใดๆ หรือไม่

1. ณ จุดนี้ คุณรู้สึกว่าโครงการจัดทำเอกสารประสบความสําเร็จหรือไม่

คำถามในอนาคต

และเช่นเคย ยิ่งเราเรียนรู้เกี่ยวกับเอกสารในโอเพนซอร์สมากเท่าไร เราก็ยิ่งต้องการเรียนรู้มากขึ้นเท่านั้น ในฤดูกาลในอนาคต เราหวังว่าจะได้เรียนรู้เกี่ยวกับสิ่งต่อไปนี้

• โดเมนของโปรเจ็กต์สัมพันธ์กับตัวเลือก DOCTYPE หรือตัวเลือกเมตริกหรือไม่
• แนวทางปฏิบัติในการว่าจ้างนักเขียนด้านเทคนิคและแนวทางการเริ่มต้นใช้งานที่มีประสิทธิภาพมากที่สุดสำหรับโครงการและการรักษาผู้เขียนเชิงเทคนิค
• ลำดับเวลาที่สมเหตุสมผลสำหรับการวัดประสิทธิภาพการจัดทำเอกสาร

แม้ว่าจะมีคำถามที่เราต้องการตรวจสอบจำนวนมาก แต่เราก็อยากสละเวลาให้กับผู้ดูแลโครงการโอเพนซอร์สและผู้บำรุงรักษาที่เข้าร่วม Season of Docs ด้วย สิ่งสำคัญสูงสุดของโปรแกรมคือการสนับสนุนโปรเจ็กต์ต่างๆ ในการแก้ปัญหาโดยใช้เอกสาร