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

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

เกี่ยวกับ Season of Docs

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

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

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

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

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

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

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

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

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

องค์กร

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

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

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

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

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

ไฮไลต์ของปี 2021

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ดูข้อมูลเฉพาะเพิ่มเติมได้ที่หน้าผลลัพธ์ของ Season of Docs 2021 ซึ่งลิงก์ไปยังกรณีศึกษาฉบับเต็มของแต่ละองค์กร

งบประมาณ

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

เมตริก

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

เมตริกที่แนะนําสูงสุด ได้แก่

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

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

ดูข้อมูลเฉพาะเพิ่มเติมได้ที่หน้าผลลัพธ์ของ Season of Docs 2021 ซึ่งลิงก์ไปยังกรณีศึกษาฉบับเต็มของแต่ละองค์กร

การทำงานร่วมกับผู้เขียนเนื้อหาทางเทคนิค

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

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

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

คําแนะนําในการจ้างงาน

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

• แชร์สื่อการรับสมัครนักเขียนเนื้อหาทางเทคนิคโดยเร็วที่สุด แม้จะยังไม่ได้รับการยอมรับให้เข้าร่วมโปรแกรมก็ตาม ขอให้ชุมชนแนะนำผู้สมัครที่เป็นไปได้
• แชร์อย่างกว้างขวางภายนอกช่องทางของโปรเจ็กต์ ใช้ภาษาที่ไม่แบ่งแยกและกระตุ้นให้ผู้สมัครจากภูมิหลังที่ขาดแคลนสมัครงานโดยตรง
• ทําความเข้าใจว่าเครื่องมือใดจําเป็นสําหรับกระบวนการสร้างเอกสาร และรับสมัครผู้เขียนเทคนิคที่มีประสบการณ์ในการใช้เครื่องมือเหล่านั้น
• กำหนดความคาดหวังที่ชัดเจนให้กับนักเขียนเนื้อหาทางเทคนิคเกี่ยวกับสิ่งที่ต้องส่งและเหตุการณ์สำคัญ ช่องทางการสื่อสารและการติดตามผล รวมถึงกระบวนการและเวลาการชำระเงิน
• ลองลงทุนกับสมาชิกชุมชนและช่วยให้พวกเขาเติบโตในฐานะผู้เขียนเนื้อหาทางเทคนิคโดยใช้ผู้เขียนเนื้อหาทางเทคนิคของ 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 ด้วย เป้าหมายหลักของโปรแกรมคือการให้การสนับสนุนโปรเจ็กต์ในการแก้ปัญหาเกี่ยวกับเอกสาร